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PREFACE 


This manual is directed toward the programmer who combines familiarity 
and access to RMS-1l1 files with a need to rapidly extract and display 
data from those files. This manual serves as both a user's guide and 
reference manual to DATATRIEVE-11. As a minimum, the reader should 
have a basic knowledge of the operating system, and should have read 
the Introduction to RMS-1l. 


Ideally, the reader is a programmer or Data Administrator experienced 
with at least one programming language such as COBOL, FORTRAN, or 
BASIC. Regardless of the amount of actual programming experience, the 
user would have studied the language reference manual and user's guide 
for at least one of these languages. Thus, it is also assumed the 
reader has acquired basic input/output and file concepts from these 
Manuals. 


This user would be experienced with various keyboards found on 
terminal devices and would be able to adapt if a given keyboard used 
the DELETE or RUBOUT key to perform an erasing function. 

Any reader lacking the above gualifications should not proceed 
further, but should consider whether it would be more appropriate to 
read instead the Beginner's Guide to DATATRIEVE-11. This latter 
Manual describes a subset of the material included here, and in more 
elementary terms. Not every user requires -- or wants to learn -- all 
the capabilities of DATATRIEVE-ll. This is something that each user's 
management must determine on an individual basis. 


The organization of this manual leads you into the full language 
capabilities first. The topics are presented in a logical learning 
sequence in Chapters 1 through 4, rather than by any alphabetical or 
implied functional order. In Chapter 5, you will find all the 
information necessary to learn to use the Report Writer facility to 
customize and print a variety of types of reports using data from 
RMS-11 files. You will find that all the syntax rules you learned in 
Chapter 3 carry over directly into the Report Writer statements. 


Chapter 6 introduces procedure definitions and presents the method 
used to invoke a procedure. 


Chapter 7 presents topics of special interest to Data Administrators 
only. The general reader will probably want to skip Chapter 7. 


Appendix A is worth your study once you have read the entire manual, 
since it provides a sample of an interactive DATATRIEVE-11l Session. 
It contains a number of additional examples of the commands, and 
should help reinforce what you have already learned. 


Appendixes B, C, and D provide summary information for convenient 
reference. Here you will find a summary of all the command formats, a 
list of DATATRIEVE-11 keywords, and an alphabetized list of all the 
error messages. 


Appendix E summarizes some COBOL rules that apply to data definitions 
used by DATATRIEVE-11l. 
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SYMBOLOGY 


Throughout this manual you will encounter certain consistent usages of 
symbols, colors, and underlining for clarifications. These 
conventions are summarized in Table P-l. 


Table P-l 
Symbols Used in This Manual 


Symbol 


RET 


C] 


} 


red print 


XXXXX 


XXXXX 


Name 


Return 


Syntax Brackets 
Square Brackets 
Braces 


Ellipsis 


Control Character 


Uppercase Letters 
Lowercase letters 


Graphic blank or 
space 


Lowercase fi 
(an integer 
number ) 


Underlining 


viii 
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Meaning 


Symbolizes the carriage 
return key or function on 
terminal keyboards. 


A syntax symbol in command 
formats that indicates 
select one of the enclosed 
entries if you wish. 


These smaller square 
brackets are keyboard 
symbols that you enter in 
the places shown. 


A syntax symbol in command 
formats that indicates 
select one of the enclosed 
items as a required entry. 


A syntax symbol denoting 
possible repetition of the 
preceding elements. 


Anything you would type on 
your terminal. All system 
printout appears in black 
print. 


Represents the CTRL key on 
many terminals. Normally 
struck in unison with the 
alphabetic character that 
immediately follows. 


Used for command names or 
other elements in the 
statements that must be 
spelled as shown. 


Used in the command syntax 
to represent items to be 
replaced by the appropriate 
names or values. 


blank or 
Only 
denote 


Symbolizes the 
space character. 
used here to 
required spaces. 


Represents an integer 
decimal number. 


Used in the command syntax 
with uppercase words to 
represent a keyword that 
must be specified in every 
use of the command, unless 
the keyword is enclosed in 
outer syntax brackets. 
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CHAPTER 1 


GENERAL CONCEPTS 


This chapter presents the definitions and fundamentals necessary to 
learn DATATRIEVE-11 quickly. DATATRIEVE-1l accepts English-like 
commands from the user and reacts by extracting data from RMS-ll 
files. It can even be directed to modify or update the file. This 
entire process occurs in interactive mode -- which means that you 
issue a command, the software responds, and you may either correct an 
error, continue by issuing more commands, or stop. Most users become 
so comfortable with the language they are able to construct the 
commands while at the terminal and adapt to the ongoing changes; they 
do not find it necessary to preplan on paper every command that will 
be entered. In this way it works much like a conversation with a 
friend, and is sometimes called a dialogue. 


Everything that can be done in DATATRIEVE-11 can be done in 
application programs. However, there are some distinct advantages to 
the interactive approach: 


@ DATATRIEVE-11 "programs" are specific to a given need. 
e DATATRIEVE-11 sessions are shorter with less coding overhead. 
-@ Time consuming compilations are not needed. 


e Users can respond to errors or unexpected variations in 
results at execution time. 


e Any particular session can be lengthened or shortened at will. 


The Report Writer facility of DATATRIEVE-11 will take data operated on 
by DATATRIEVE-1l (or straight from an RMS-11 file) and print it to 
conform to user-specified formats. : 


1.1 INTRODUCTION TO DATATRIEVE-11 INQUIRY FACILITIES 


You direct DATATRIEVE-11 with English-like commands. DATATRIEVE-11 is 
a command interpreter that both interprets and acts on each statement 
as received. Section 2.4 and Chapter 3 provide you with all the common 
rules that apply to using the commands. Your major task will be to 
formulate the commands that express your desires accurately to 
DATATRIEVE. A number of requirements can be fulfilled by alternate 
combinations of commands. This means that the "right" solution to a 
DATATRIEVE-11 problem is any solution that works. 


When you make mistakes, you will be pleased to find that the 
consequences are seldom very severe. You can always go back to where 
you started and issue a corrected version of the command(s). This may 
be a bit of a nuisance, but at least you will not have lost or 
destroyed your data in the meantime. 
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There will be certain sequences of commands that must be issued on a 
“recurring basis at every installation. As a result, DATATRIEVE-1l has 
a feature that permits the definition and use of procedures. These 
are nothing but DATATRIEVE-11 commands that are generalized and saved 
with a special name, a procedure name. Later at any time ina 
DATATRIEVE-1l1 sequence of commands you can invoke the procedure by 
calling out its name. This saves you some redundant typing. It also 
provides a means to establish and distribute more complicated sequences 
of commands so that everyone within the installation can benefit from 
them without necessarily having to reinvent them. Chapters 6 and 7 
provide more discussion of procedures. 


1.2 INTRODUCTION TO DATATRIEVE~11 REPORT WRITER FACILITIES 


Once you have successfully invoked DATATRIEVE, you can specify that 
you wish a certain format of report printed on one of the available 
devices. The data to be used in the report may come directly from the 
RMS-11 files or may have been preselected and manipulated through a 
series of DATATRIEVE-11 commands. 


Each report specification is enclosed between a pair of commands: 
REPORT and REPORT END. We will call this entire grouping an RW 
Sequence, where RW refers to the Report Writing facility of 
DATATRIEVE-11. 


More than one Report Writer exercise can be incorporated at a time in 
a given session. In fact, it is possible to bounce back and forth 
between inguiry processing and RW processing. The only restriction on 
intermixing inquiry processing and RW statements in a session is that 
inguiry processing statements must not occur inside an RW sequence. 


1.3 SAMPLE DATA FOR EXAMPLES 


Throughout the manual the examples use one set of sample data. This 
data is depicted in Figure l1-l. 


The sample data is based on an inventory of yachts, as kept by 
Star-Key Marina, Inc. Seven pieces of information are kept for each 
type of yacht: the manufacturer, the model number, the rig type, the 
length-over-all, the displacement (or weight), the beam size, and the 
price. 


1.4 DEFINITIONS: FILES, DOMAINS, COLLECTIONS, RECORDS, AND FIELDS 


This section defines the terms domain, collection, record, file, and 
field. 


Records are groups of related items of data that are treated as a 
unit. For example, all the pieces of data describing a model of yacht 
in the marina could be grouped to comprise that yacht's record. 


Each of the individual pieces of data in a record is referred to as a 
field. For example, the yacht's model number, length, and price are 
all potential fields in the yacht record. 
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The term files is used to refer to the logically related groups of 
data that are kept by RMS-11. For example, we might put all of the 
yacht records for the current inventory at Star-Key Marina, Inc., into 
one file. 


Domains are named groups of data containing records of a single type. 
An RMS-1l1 domain consists of all the records in a given RMS-1l file. 
In this case, we could say that all the yacht records for the current 
inventory are kept in the YACHTS domain. The number of records in any 
domain may change as new records are stored or old records are erased. 


A record collection is a subset of a domain. It may consist of no 
records, one record, or up to all the records in the domain. Using 
our previous example, we could say that all the yachts manufactured by 
Grampian could be made to form the Grampian-collection, while those 
yachts manufactured by Islander could be used to form the 
Islander-collection. To carry this example one step further, if the 
inventory is currently out of stock of yachts manufactured by 
Seaworthy, the Seaworthy-collection will be empty, or null. 


1.5 INTRODUCING THE DATA DICTIONARY 


The Data Dictionary is a location where the definitions for 
procedures, records, and domains are kept in a standard fashion by 
DATATRIEVE-11. The Data Administrator will be concerned with the 
creation -and maintenance of Data Dictionary information. Certain 
users will be able to display certain information from within this 
dictionary, but only management will be concerned with defining it. 


1.6 PROCESSING A FILE AS A COLLECTION 


The most important concept to master is collection processing. 

DATATRIEVE-11 operates on collections of records taken from the files. 
To get down to the level of record processing you must first use the 
FIND and SELECT commands to gather the collection and extract desired 
records. DATATRIEVE provides a collection cursor to keep track of 
your place in the collection. Figure 1-2 illustrates the cursor as a 
place marker. You will learn how to manipulate the cursor, moving it 
through the collection, from the first, to possibly the next or the 
nth record, all the way to the last. Your moves need not always 
follow a forward direction; you can move about the collection at 
will. 


In most DATATRIEVE-11 operations, the files are never changed, but a 
great deal of manipulation occurs on the collections. Thus, the 
collections can be thought of as just a sort of temporary storage, 
kept for immediate purposes, and then released. 
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LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM FRICE 
ALBERG 37 MK II KETCH 37 207000 12 $369951 
ALBIN 79 SLOOP 26 49200 10 $17%900 
ALBIN VEGA SLOOF 27 39070 O08 $18%600 
AMERICAN 26 SLOOP 26 4000 08 $97rB95 
AMERTCAN 26-MS M/S 26 29IJ00 O08 $187895 
BAYFIELD 50/32 SLOOP 32 99500 10 $32%9875 
CAFE DORY 28 SLOOP 28 92000 OF $21%9990 
CAFE DORY TYPHOON SLOOP 19 12900 06 $49295 
CAFE DORY 20 SLOOF 25 47000 07 $82995 
CARIBBEAN 35 SLOOF 33 187000 11 $37,850 
CHALLENGER 32 SLOOP 32 129800 11 $31,835 
CHALLENGER 35 SLOOP 35 147800 12 39215 
CHRIS-CRAF CARIBBEAN SLOOP 35 187000 11 $37,850 
CLIPPER CM 30 SLOOF 30 3800 08 $92500 
CLIPPER CM 32 SLOOP 32 49500 08 $122950 
EASTWARE! HO M/S 24 72000 O09 $15%900 
GRAMPIAN 26 SLOOP 26 39600 O08 $11%495 
GRAMPIAN 28 SLOOP 28 69900 10 $149475 
GRAMF IAN 34 KETCH 33 127000 10 $29%675 
HUNTER 27 SLOOP 27 69500 O09 $1429999 
I. TRADER 3? KETCH 36 18%600 12 $39500 
IRWIN 37 MARK II KETCH 37 209000 11 $36%950 
IRWIN 25 SLOOP 29 99400 12 $10%950 
ISLANDER 28 SLOOP 28 39794 10 $15%908 
ISLANDER BAHAMA SLOOF 24 42200 08 $469500 
LINDSEY 39 M/S 39 14/500 12 $35,900 
RYDER S. CROSS SLOOF 31 13¥600 00 $32%500 
SABRE 28 SLOOP 28 727400 OF $22%000 
SALT 19 SLOOP 20 22600 07 $69590 
TANZER 26 SLOOF 26 429350 O09 112750 
TANZER 28 SLOOP 28 69800 10 #177500 
VENTURE 21 SLOOF 21 1%500 07 $2823 
VENTURE 222 SLOOP 22 29000 07 $39564 
WESTERLY CENTAUR SLOOP 26 69700 O08 $15%245 
WINDFOWER IMPULSE SLOOP 14 650 07 $3%7500 
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Figure 1-1 Sample Data 
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CAPE DORY 28 


BOMBAY CLIPPER 





BAYFIELD 30/32 


AMERICAN 26-MS LAST 


AMERICAN 26 


ALBIN BALLAD NEXT 


ALBIN VEGA CURRENT 


ALBIN 79 


ALBERG 37MKIl 


Just aS you would expect, the FIRST record of the collection is the 
first one encountered when it was being established or collected. The 
record numbered with @ in Figure 1-2 identifies the first record in 
this example. 


The NEXT record is always the one immediately after the CURRENT one. 
In the figure, the CURRENT record is the sixth one, so the NEXT record 
must be the seventh. 

We have been referring to records according to their numeric position 
in the collection, that is, sixth, seventh, and so forth. This is a 
proper form of reference, and in the DATATRIEVE-1l1 language you will 
use digits for the position number whenever a format specifies the nth 
record. 


The LAST record is the one located at the very end of the collection. 


If there happen to be no records at all in a collection, we say the 
collection is null, and the collection cursor will have to be null, 
too e 


Generally, you will work on just one collection at a time, the CURRENT 
one. However, there is the facility to name a collection and refer 
back to it later in the same session, if you feel that it has enough 
importance or probability of reuse. (See Section 4.4.) 


Thus, you may find yourself working with a number of collections, one 
of which is the CURRENT one, the one most recently the object of a 
FIND command. Each of the collections has its own collection cursor 
and may have a designated CURRENT record, as well. However, only one 
collection may be CURRENT at a time. 
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The lifetime of any collection is limited to a given’ session. 
Collections cannot be saved, nor can they be shared by several users. 
However, you can always reproduce a collection of identical 
characteristics (although not necessarily identical records since the 
files can change in the interim). You simply repeat the sequence of 
FIND command(s) used initially to establish and/or refine the 
collection. If you find this to be a frequently recurring 
requirement, perhaps your installation should define the steps as a 
procedure. (See Chapter 6 and Section 7.2.) 


Collections may be ordered on command. When you sort a _ collection, 
you may well change the position a particular record holds. 


CHAPTER 2 


USING DATATRIEVE-11 


In this chapter you will learn how to know when DATATRIEVE-11 is ready 
to accept a command, how to terminate a session, what to expect in the 
error messages, and the general mechanics of entering commands. 
However, the commands are described in later chapters. 


2.1 INVOKING DATATRIEVE-11 


Once you have logged onto your system and instructed the operating 
system to invoke DATATRIEVE-i11 according to the standard operating 
system procedures, you will see the prompt DTR> on your terminal. 


This means you are ready to enter a DATATRIEVE-11 command. 


2.2 STOPPING 


You may leave a DATATRIEVE-11 session at an 
command (Section 4.2) or the CTRL Z (“Z) ch 


y time by means of the EXIT 
aract 


; 
i 

; : 

racter combination. 


2.3 ERROR MESSAGES 


Because you operate in interactive mode, you get immediate 
notification when an error is detected. This gives you the following 
options: 


e revise your work (if this was a major error), 
@ correct the problem in the last command, or 
@e terminate the session. 


All error messages are listed in alphabetical order in Appendix D. 
You will observe that the messages are sentence-like and quite 
descriptive. There will be no need to "decode" an error code, aS you 
may have done in some other languages. 


2.4 ENTERING COMMANDS 


As you learn the commands in the following chapters, you will find 
certain common rules apply to entering them. For example, you can 
only enter a command after the prompt DTR>. Furthermore, you must 
terminate a command with a final carriage return. Once a command is 
entered, DATATRIEVE-11 begins execution immediately. If you have made 
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an error, but no significant changes were made to the collection, you 
may generally simply reissue the command in corrected form to obtain 
the desired results. 


CHAPTER 3 


SYNTAX RULES FOR DATATRIEVE-11 COMMANDS 


This chapter presents all the basic rules that apply to the 
construction of DATATRIEVE-11l commands. You must understand the 
significance of spelling, spacing, syntax symbols, and sequence when 
using the commands. You will learn what characters are permitted in 
the commands, how to form names and literals, how to insert comments, 
and how to continue and terminate command lines. You will also see 
how to interpret syntax symbols, how to delimit (separate) the parts 
of a command, and what the keywords in the commands are. 


3.1 SEQUENCE OF COMMANDS 


There are just a few restrictions regarding the sequence of the 
commands. EXIT is always the last command. READY is often the first 
command, but it could be preceded by others. Beyond that, you can 
intermix commands with each other, and likewise, you can intermix RW 
commands with each other, with a great deal of freedom. However, as 
mentioned in Chapter 1, once you begin the specification of a report, 
you cannot introduce other commands until the REPORT END command is 
processed. 


3.2 SPELLING 


Spelling is critical: you must enter commands as they are shown in 
their "Format" description. As a general rule, command names or 
elements may not be abbreviated unless the particular command 
description tells you to do so. 


3.3 SPACING 


DATATRIEVE-11 is a free-form language, which means that you may have 
any number of intervening spaces or tab characters between language 
elements. Since DATATRIEVE-11 is English-like, the examples generally 
show single spaces between elements. 


3.4 SPECIAL SYMBOLS -- BRACKETS, BRACES, ELLIPSIS, UPPERCASE, AND 
LOWERCASE 


The preface introduced these special symbols, but it may be helpful to 
supplement the definitions with examples. Special symbols are used in 
the syntax descriptions to clarify proper usage of the command 
elements. While they are discussed individually here, you will note 
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in Figure 3-1 that they can be combined in a given syntactical 
expression in numerous ways, even nesting. 


Syntax Brackets ([ ]) denote items that are optional. If more than 
one item is enclosed in brackets, you may chose one (or none) of the 
items. 


Square Brackets ([ ]) denote the bracket symbols on the keyboard and 
are required where shown. 


Braces ({}) enclose one or more items that are required. If more 
than one possible entry is shown, you must include one of the choices, 
but you can specify no more than one. 


Ellipsis (...) imply that you can choose to repeat a version of the 
immediately preceding command element. In DATATRIEVE-11 there are no 
restrictions on the number of repetitions, unless you are explicitly 
told so. Watch for punctuation characters needed to serve as 
separators for the repetitions. Note that repetitions only occur at 
your option. 


Uppercase letters denote required words when underlined. When not 
underlined, these words are optional. 


Lowercase letters are used with generic terms that must be replaced by 
the appropriate names or values. 


Underlining (__) denotes that the uppercase word is required in every 
use of the command or statement, unless enclosed in outer brackets. 


Figure 3-1 illustrates a fairly complex syntactical structure, 
employing all these symbols in an English sentence rather than a 
command. Observe how the symbols can be nested. Wherever nesting 
occurs, the meaning of the outermost pair of symbols prevails. Thus, 
when a seemingly required item inside braces occurs inside a pair of 
outer brackets, the entire group is considered to be optional. 


As you study Figure 3-1, notice the large number of legal sentences 
that can be constructed to conform to the syntax; only a few 
possibilities are shown here. 


Later, when you see these same symbols used in actual DATATRIEVE-11 
command definitions, keep in mind the large number of combinations of 
command elements they imply. Do not be concerned that you will need 
to enter these special symbols as part of the command. They only 
exist as part of the description of the command, as a sort of code to 
indicate a number of ways you can choose to construct each command 
from its parts. 
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Assume the following syntactical structure: 


LATE BETTY 


THE FIELD MARY 


JOHN PLAYS Ee [[FORGETS HE HAS/ A DATE WITH SUSIE --- J, AND LOSES ALL. 


The 


THE HORSES GAIL 


following sentences are among the many possibilities the user 


could construct: 


JOHN 





JOHN 


JOHN 


PLAYS, AND LOSES ALL. 


None of the optional bracketed items is included; only the 
required underlined words in uppercase are kept. 


PLAYS THE HORSES, AND LOSES ALL. 


An object word for PLAYS is supplied, but the bracketed FORGETS 
clause is omitted. 


FORGETS HE HAS A 


The optional bracketed items after PLAYS are omitted, but the 
FORGETS clause is added. 


PLAYS THE FIELD, FORGETS HE HAS A DATE WITH SUSIE, AND LOSES ALL. 
All options included except the repetition. 


PLAYS BASEBALL, FORGETS HE HAS A DATE WITH BETTY, A DATE WITH 
GAIL, AND LOSES ALL. 


Observe the substitution of BASEBALL for the lowercase word 
sport-name and the repetition at the site of the ellipsis. 





Figure 3-1 Illustrating Syntactical Symbols 
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3.5 CHARACTER SET 
The character set consists of the letters A through 2Z, numbers 0 


through 9, and certain special symbols. See Table 3-1. 


Table 3-1 
DATATRIEVE-11l Character Set 


WODWHAUBWNHOKHONK XMS ACH 


Mm TVA Ih-— 2. eI Foto et se 


A 
B 
C 
D 
E 
F 
G 
H 
I 
J 
K 
L 
M 
N 
O 
P 
Q 
R 
Ss 





3.6 COMMENTS 


You may introduce a comment anywhere in your session if you like, by 
keying an exclamation point character (!), following it with text, and 
terminating with a carriage return (C#)). The text may consist of 
any characters in the character set including the exclamation point. 


Comments may begin anywhere on an input line and are not required to 
start at the beginning of the line. 


The value of comments diminishes in an interactive environment. You 
may find you wish to include them in indirect command files (Section 
7.1). However, you will find that if you put them in your’ procedure 
definitions (Section 7.1.3), they are not retained in the Data 
Dictionary. 
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3.7 NAMES 


Names are constructed from the letters A through Z, numbers 0 through 
9,.. and the special character, hyphen (-).. The construction of names. 
is subject to five rules: 


1. Every name must begin with a letter. 
2. Names must never end with a hyphen. 


3. Names can only be continued from the end of one input line to 
the beginning of the next by means of a hyphen, as will be 
explained in Section 3.9. 


4. You must be careful when creating names to avoid the 
DATATRIEVE-11 keywords. (See Section 3.11.) For your 
convenience, these special names are also listed 
alphabetically in Appendix C. 


5. Names of records, domains, procedures, and collections are 
kept in the Data Dictionary and are subject to a size 
limitation of 30 characters. 


3.8 LITERALS 


There are two categories of literals: alphanumeric and numeric. 
Thus, different rules apply for specifying each. 


Alphanumeric literals may consist of alphabetic, numeric, and special 
characters. All alphanumeric literals must be enclosed in quotation 
marks ("). For example, if you use the phrase BUILDER EQUAL "O'DAY", 
"O'DAY" is an alphanumeric literal. Similarly, in MODEL EQUAL "37 MK 
Ii", "37 MK II" is an alphanumeric literai. To include a quotation 
mark as a legal character within an alphanumeric literal, use two 
consecutive quotation marks. For example, you might want to display 
an alphanumeric message, "CAPT. JACK SAYS, ""TIME TO REORDER""", such 
that TIME TO REORDER would appear in quotes. 


Combinations using the CTRL (*) character are not permitted as special 
characters in an alphanumeric literal. 


Numeric literals consist of digits and an optional decimal point (.), 
and they are written without quotation marks. For example, you may 
use the phrase, BEAM EQUAL 12. Here, 12 is a numeric literal. If the 
decimal point is included, it must not be the first character in the 
number. Thus, 0.5 is permitted as a numeric literal, but .5 is not. 


SYNTAX RULES FOR DATATRIEVE-11 COMMANDS 


3.9 CONTINUATION LINES -- CARRIAGE RETURN ( C=) ) 


Some of the DATATRIEVE-11 statements can become longer than a_ single 
line length. DATATRIEVE-l1l permits continuation lines. You simply 
enter a carriage return (Crt) ) as you approach the end of each line 
and continue the statement on the next line or lines. 


DATATRIEVE is able to recognize all the possible elements in a command 
and to interpret whether there should be more input to follow any 
given carriage return. As proof of this, you may see DATATRIEVE-11 
responses that say: [LOOKING FOR element-name] where element-name is 
the syntactical element that DATATRIEVE-11 has determined should 
follow the preceding portion of a command. 


CAUTION 


If you enter a carriage return at a 
point where a logical termination could 
occur, DATATRIEVE assumes it has’ found 
the termination and looks no further. 
You may use the hyphen (-) to remove all 
ambiguity: a hyphen preceding a 
carriage return always implies a command 
continuation to DATATRIEVE. However , 
you should not continue more than _ two 
successive lines with hyphens. 


Also note that the hyphen provides the only proper way to continue a 
literal or mame from one line to the next. To continue a hyphenated 
name, such as SMALL-YACHTS, you could specify any of the following 
forms, Or variations of them. 





SMALL-~- 
-YACHTS 





or 


SMALL~= Cer ) 
| YACHTS 
or 


SM=— © eet 3 


ALL-YACHTS 


Figure 3-2 illustrates these concepts with an ordinary English 
sentence. 
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Assume the sample sentence: 


JOHN WENT TO THE OFFICE AND RAN INTO MARY 


JOHN Cer) Subject, but no verb, so continue. 
WENT Caer) Missing the object, continue. 

TO THE OFFICE Ce) Sentence appears complete, stop. 

AND RAN INTO MARY Ct) Attempt to process as a new sentence. 


To remedy the premature termination, try this instead: 


JOHN Caer) 
WENT Caer) 
TO THE OFFICE AND C2) Now it is obvious there is more. 
RAN Ca) 
INTO (rer) 
MARY (ret) Structure appears complete, stop. 


You could have used a hyphen (-) after "OFFICE" 
to indicate continuation: 


JOHN Cer) Subject, but no verb, so continue. 
WENT Caer) Missing the object, continue. 

TO THE OFFICE-(C#) Hyphen before return, continue. 
AND RAN INTO MARY Ct) Structure appears complete, stop. 





Figure 3-2 Example of Carriage Return Interpretation 


3.10 COMMAND TERMINATION--SEMICOLON 


Since DATATRIEVE recognizes the command elements, it is not necessary 
to terminate each command with some form of punctuation such as a 
semicolon. However, the option exists for you to specify the 
semicolon, if you desire, as the formal designation of command end. 
Two commands, DELETE and DEFINE, require the semicolon. 


If you want to issue more than one command per input line, you must 
use the semicolon to separate the commands. Furthermore, DATATRIEVE 
will not begin to process any commands on the same input line until a 
carriage return is detected. 


Spaces or tab characters at the end of a line are ignored. 


3.11 KEYWORDS 


Keywords are language elements that have a specific meaning to 
DATATRIEVE-11. If you use them in any other context, you may confuse 
DATATRIEVE about your intentions. Thus, it is a good policy to avoid 
the use of these words as names of domains, procedures, records, 
fields, and collections. 


The full list of keywords is reproduced in Table 3-2 and Appendix C. 
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Table 3-2 
Keywords 





























ABORT 
ADVANCED 
ALL 

AND 

ASC 
ASCENDING 


BETWEEN 
BOTTOM 


CHARACTER 

COL 
COLLECTIONS 
COLUMN 
COLUMN-HEADER 
COLUMNS-PAGE 
COMP 

COMP-1 

COMP-2 

COMP-3 

COMP-5 

COMP~6 

COUNT 

CURRENT 

DATE 
DECREASING 
DEFINE 
DEFINEP 
DELETE 
DELETEP 





3.12 DELIMITERS 


Delimiters are required around keywords, names, and 
separators, and 


delimiters are 
choices: 


@ the space, 






DESC 
DESCENDING 
DISPLAY 
DOMAIN 
DOMAINS 
EDIT-STRING 
ELSE 

END 
END-PROCEDURE 
EQ 

EQUAL 

ERASE 
EXCLUSIVE 
EXIT 

EXTEND 

FILL 

FIND 

FINISH 

FIRST 

FOR 

GE 
GREATER-EQUAL 
GREATER-THAN 


INCREASING 
Is 
JUSTIFY 
LAST 

LE 
LEADING 


e the tab character, and 


e the carriage return. 


Any given DATATRIEVE-11 session may use all 


times in many different places. 





LESS-EQUAL 
LESS-THAN 
LINES-PAGE 
LT 

MAX 
MAX-LINES 
MAX-PAGES 
MIN 

MODIFY 

NE 
NEW-PAGE 
NEW-SECTION 
NEXT 

NO 

NO-DATE 
NO-NUMBER 
NOT 
NOT-EQUAL 
NUMBER 


PRINT 
PROCEDURE 
PROCEDURES 
PROTECTED 

PW 
QUERY-HEADER 
QUERY-NAME 
READ 


you may 


literals. 


select any of the three 


three delimiters 





READY 
RECORD 
RECORDS 
RELEASE 
REPEAT 
REPORT 
REPORT-HEADER 
REPORT-NAME 
SELECT 
SELECTIVE 
SEPARATE 

SET 

SHARED 

SHOW 

SHOWP 

SIGN 

SKIP 

SORT 

SORTED 

SPACE 

STORE 

TAB 

THE 

THEN 

TOP 

TOTAL 
TRAILING 

UIC 

USAGE 

USING 

VERIFY 

WITH 
WRITE 


These 


many 
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3.13 SEQUENCE OF COMMAND ELEMENTS 


Each possible command element has a position in the command format. 
This... relative location is always illustrated when the command formats. 
are given. It is extremely important that you obey this sequence when 
you formulate your commands. When you decide to omit one of the 
optional elements, just leave its relative position in the command 
empty, but proceed to the remaining elements in the left-to-right 


sequence. 


CHAPTER 4 


COMMANDS FOR INQUIRY & UPDATE 


This chapter presents the commands that are part of the DATATRIEVE-11 
facility for inquiry and update. 


4.1 STARTING A DATATRIEVE-11 SESSION WITH READY 


As soon as you have successfully invoked DATATRIEVE-1l and _ have 
obtained the DTR> prompt, you are able to enter your first command. 
If you have been away from the system for a while, you may wish to 


refresh your memory by means of the HELP command that is described as 


i 
the very last item in this chapter. (See Section 4.14.) 


The operations you are about to attempt will probably require the use 
of one or more domains. Before you can use any domain you must ready 
it, so you will probably want to issue a READY command as one of your 
commands, if not the first. The purpose of readying a domain is to 
claim it for your use. This means that if other users want to use it, 
too, they may be subject to certain restrictions. It is important 
that any shared resource be handled according to certain rules. 


The data processing management at your facility will have given 
considerable thought to whether certain resources may be shared. One 
issue is whether to restrict the ability to change any of the record 
fields in a file to only certain users. Another concern is whether to 
permit sharing at all. By the time you are ready to run your first 
DATATRIEVE-11 request, these issues should be resolved. 


The types of access modes and modifiers are described in Table 4-l. 
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Table 4-1 
Types of File Access Modes and Modifiers 


fp moastier fs meaming 


SHARED 














Any other user may have concurrent access to the 
records in this domain, for any purpose. 








PROTECTED Any other user may access, but not concurrently 
write, modify, or extend (add) records in this 


domain. 





EXCLUSIVE No other user may concurrently execute a READY 


for this domain -- for any type of access. 















Mode Name Meaning 





READ Retrieve only. 


MODIFY Retrieve and change only. 








WRITE Retrieve, change, add, or delete. 





EXTEND Add only. 


NOTE: The Data Administrator will have some control over 
which modes of access (READ, MODIFY, WRITE, or EXTEND) 
are permitted for each domain. (See Chapter 7.) 
However, you are the only one controlling the acceptance 
of the access modifiers (SHARED, PROTECTED, or 
EXCLUSIVE). 
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READY 


Purpose 
This command informs the system that you expect to 
reference a certain domain. At the same time, you can 
declare how you intend to use the domain. For example, 
you can indicate that you want to just read from it, or 
that you expect to modify it, or that you will want 
exclusive use of it. 
Format 
READ 
SHARED MODIFY 
READY domain-name-1 [(password-str-1)] | PROTECTED WRITE 
EXCLUSIVE EXTEND 

1. You must supply a domain-name, and it must name a 
domain that exists in the Data Dictionary and on 
the RMS-11 files. 

2. You may optionally wish to specify the access 
modifiers and/or access modes that you expect to 
use. See Table 4-1 for a description of each. 

3. In some. cases it may be necessary to know a 
password to gain access to a particular domain. If 
you are given a password to specify, be sure _ to 
enclose it in parentheses. If you enter an 
asterisk (*) for your password, you will be 
prompted to supply a password. In this mode your 
password specification will not be echoed on your 
terminal device to ensure greater assword 
security. 

4. If none of the access modifiers or modes is 
specified, it is assumed you wish to ready the 
domain for PROTECTED READ. 

Reguirements 
None. 
Restriction 

You cannot issue a READY command in aé_e procedure 

definition (Section 7.1.3), a BEGIN-END Block (Section 

4.13.1), or THEN statement (Section 4.13.4). 

Prompts & 
Responses 

None, unless you specify an asterisk (*) for the 

optional password. This will cause the following prompt 

to appear: 
PLEASE SUPPLY PASSWORD: 
Effects 


1. The domains are checked for existence and 
availability. 


Examples 


Hints 
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2. DATATRIEVE checks an internal password table for 
the named domain to ensure that you are allowed the 
type of access mode requested for that domain. 


3. The record definition for this domain is also 
checked for existence. 


4. You can only ready one domain at a time with this 
command. However, you can use the command multiple 
times in a session to ready a number of domains at 
once, 


5. If you READY the same domain again but give 
different access qualifiers, the last READY to be 
executed prevails. 


The following example readies the domain YACHTS (yacht 
records) for exclusive use by this user and allows the 
domain to be read, modified, erased, and/or extended. 
Since this is the full range of access capabilities and 
the most restrictive access modifier, it is logical to 
assume a password is necessary. Your password is 
FAIRWINDS. 


DTR>READY YACHTS (FAIRWINDS) EXCLUSIVE WRITE; Cer) 


The following example illustrates how to ready the same 
domain for shared read-only access when no password is 
required: 


DTR>READY YACHTS. SHARED READ? ‘Rr? ) 


You should adopt the practice of only readying those 
domains you really intend to use. However, since very 
little can be done in a DATATRIEVE session unless’ you 
have performed a READY, you will probably also want to 
adopt the habit of issuing the READY command(s) at the 
very beginning of the session. 


It is also good practice to be as unrestrictive in the 
access mode specification as you can afford to be. For 
example, if you insist on demanding that the domains 
you use be kept EXCLUSIVE, you can hurt system 
performance for other users that could otherwise be 
sharing the domain. 


Finally, if you only intend to retrieve records from 
the domain, keep in mind that READ mode is more 
efficient for this purpose than either WRITE or MODIFY 
mode. Selecting either of the latter two just to 
retrieve is overkill. 


You can confirm that a domain has been readied by means 
of the SHOW READY command described in Section 4.3. 
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4.2 ENDING A DATATRIEVE-~11 SESSION -- EXIT 


If at any time you wish to leave your terminal or stop a DATATRIEVE 
session, you. should know how to use the EXIT command. This command 
lets you terminate any session gracefully. It 1s the proper way to 
finish all sessions, and assures you that no unauthorized user can 
gain access to domains you have readied from your terminal. It is 
also the most considerate action to take so that domains are freed up 
for other users to gain access. It is good practice not to leave the 
terminal unless you have performed an EXIT command. 








EXIT 


Purpose 


Format 


Requirements 


Prompts & 
Responses 


Effects 


Example 


Hint 
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When you execute this command, you close 


DATATRIEVE-1l session. 


EXIT 


You may issue this command at any time in 
DATATRIEVE-11 session, 


No prompting messages appear, but you will be informed 
that the session is terminated. The response assumes 


the form: 


BYE 


1. DATATRIEVE-11 processing is terminated. 


2. Any domains that had been readied are automatically 
closed, and all collections established in this 
session are released. This is true for both the 


named and unnamed collections. 


3. You cannot issue another DATATRIEVE-ll1 command 


until you reinvoke DATATRIEVE-1l1. 


DTR>EXIT; 


BYE 


You can accomplish the functions of the EXIT command 


with a CTRL Z (°2Z). 
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4.3 GETTING AN OVERVIEW OF YOUR DATA -- SHOW 


If at any time you begin to wonder about the contents of a particular 
-domain..-or.. record, —-you--May.... want...to--.issue-.-the- SHOW.-command.....Each. 
installation can provide its users with current printouts depicting 
the domain and record definitions that will be used. However, it is 
the SHOW command that is used to generate them, and it is always 
helpful to know how to use this command yourself. 


In some installations domain and record information will be quite 
static, while in others, there may be frequent changes. When in 
doubt, it is easy enough to request a copy with the SHOW command. 


Furthermore, since a collection is a temporary formation, you may want 
to monitor your collections yourself. All these capabilities, and 
more, are possible with the SHOW command. 


SHOW 


Purpose 


Format 
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This command requests a copy of the summary details 
Maintained in the Data Dictionary for your data. You 
May request to see all the information maintained, or 
you may just request to see specific portions of it. 
For example, you might limit your review to the domain 
details, or you might restrict it even further to only 
one particular domain, collection, or record. 


SHOW show-item-1 [,show-item-2...] 


l. You must supply at least one show-item, and it must 
be one of the following possible choices; 


PROCEDURES 

DOMAINS 

COLLECTIONS 

RECORDS 

ALL 

CURRENT 

READY 

procedure-name-1 [(password-str-1)] 
domain-name-1 [(password-str-2) 
record-name-1 (password-str-3)] 
collection-name-l 


Observe that three of the possible show-items may 
. take an. optional password. string. 


2. You may optionally wish to request additional 
information by appending one or more show-items. 


3. If you specify PROCEDURES, DOMAINS, COLLECTIONS, or 
RECORDS, your display will show the names of the 
defined procedures, defined domains, established 
collections, or defined records, respectively, as 
they exist at this point in time, 


4. If you specify ALL, your display will contain the 
names of all the defined procedures, defined 
domains, established collections, and defined 


5. If you specify CURRENT, your display will provide 
only the information describing the CURRENT record 
collection. 


6. If you specify READY, your display will identify 
the names of all domains that are presently ready, 
their file type, access mode, and access modifier. 


7. %$If you name a specific procedure, domain, 
collection, or record, you will be given 
information regarding just that particular item, 
provided it is not protected from your view. 
Procedures, domains, and records can be protected 
so that only users with password knowledge can view 
or change them. 


Requirements 


Restriction 


Prompts & 


RDea-- -— = 


Effects 


Examples 
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8. If you want, you may separate each of the 
show-items by a carriage return ( ). 
DATATRIEVE will execute each part of the command up 
to.-each.carriage return, and will then come back to 
look for more show-items. 


The format of the SHOW command that specifies a 
resource-name (where domains, records, and procedures 
are the resources) requires that the issuer have access 
privileges. These checks are part of the data 
protection features described in Chapter 7. 


The only other prerequisite concerns the specification 
CURRENT. You should only specify SHOW CURRENT when you 
have established a CURRENT collection with the FIND 
command. Section 4.4 describes the various FIND 
commands. 


You must not use this command within a procedure. (See 
Section 7.1.3.) 


If you specify an asterisk (*) for the optional 
password, you will be prompted to specify the full 
password by the message: 


PLEASE SUPPLY PASSWORD: 


Otherwise, no prompting messages appear, but you wiii 
find the display occurring automatically on your 
terminal device. 


1. If you are deemed to have access privileges for a 
named resource (such as a particular’ record, 
domain, or procedure definition), the results of 
the request appear, in the order of the show~items, 
on your terminal device. The format of the output 
is explained by Figure 4-1. 


2. For the other types of show items, no checking is 
necessary; the results appear, in the order of the 
show-items, on your terminal device. See Figure 
4-1] for a sample of the printout format. 


3. There is no effect on the collection cursor. 


The following example displays the names of all the 
procedures, domains, collections and records. 


DTR>SHOW ALL; 


Hints 
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The following example illustrates how to display just 
the record definition for the record named 
COBOL-YACHTS. Assume that your password is SUNNY-DAY. 


DTR>SHOW COBOL-YACHTS (SUNNY-DAY); 


If you are going to use a password with the SHOW 
resource-name form of the command, consider specifying 
just an asterisk in parentheses (*). DATATRIEVE will 
respond by requesting the full password, but will not 
echo the characters you enter. This affords greater 
password security. 
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DTR> SHOW DOMAINS 

DOMAINS: 
THINGS-TO-DO 
DICT-DOMAIN 
FORTRAN=YACHTS 
COBOL-YACHTS 
BOATS 
FEATURES 
DATA-TYPES 
MESSAGES 
RMS-MSGS 
COMF-SCALE 
MESSAGES-SHIP 
YACHTS 


DTR>SHOW YACHTS 

DOMAIN YACHTS 
USING YACHT ON 
YACHT. DAT} 


“DTR> SHOW YACHT 
RECORD YACHT 
USING 
O1 BOAT. 
03 TYPE. 

O& MANLIFACTURER PIC X10) 
QUERY-NAME IS BUILIIER. 

O06 MODEL FIC X(10), 

03 SPECIFICATIONS 

QUERY-NAME SFECS. 

O6 RIG PIC X¢4). 

06 LENGTH-OVER-ALL FIC XXX 
QUERY-NAME IS LOA. 

O06 DISFLACEMENT FIC 99999 
QUERY-HEADER IS "WEIGHT" 
EDIT-~STRING IS ZZ»ZZ9 
QUERY-NAME IS DISF. 

O6 BEAM FIC 99. 

O& PRICE FIC 99999 
ENIT-STRING IS $$¢7$$% 45 


QTR: READY YACHTSs FIND) THE YACHTS WITH FRICE =03 


C35 RECORDS FOUNDI 
DTR» SHOW CURRENT 


COLLECTION CURRENT 
DOMAIN? YACHTS 
NUMBER OF RECORDS: 35 
NO SELECTED RECORD 


UTR: SHOW COLLECTIONS 
COLLECTIONS! 
CURRENT 


‘NTR: SHOW REATIY 
READY DOMAINS: 
YACHTS: RMS INDEXED, FROTECTED READ 


OTR: SHOW POUNDS-FER-FOOT 


PROCEDURE FPOUNDS-FER-FOOT 
DISP/LOA C*FOUNTIIS"/"PER'/"FOOT") USING Z(5) 


Figure 4-1 Sample Displays Resulting from the SHOW Command 
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QTR>SHOW ALL» 

DOMAINS? 
THINGS-TO-~-DO 
DICT-LOMAIN 
FORTRAN-YACHTS 
COBOL-YACHTS 
BOATS 
FEATURES 
DATA-TYFES 
MESSAGES 
RMS~MSGS 
MESSAGES-SHIP 
YACHTS 

RECORDS; 
THING-TO-DO 
DICT-REC 
FORTRAN-YACHT 
COBOL~YACHT 
FEATURE~RECORD 
DATA-TYPE-RECORD 
RMS~-MSGS-RECORD 
MSG-RECORD 
MSG-SHIP-REC 
YACHT 

PROCEDURES $ 
REF ORT 
FOUNDS-FPER-FOOT 
LOA~REFORT 
MESSAGE-REFORT 
FEATURE-REFORT 
MESSAGE-LISTINGS 
LIST-MESSAGES 
FRICE-PER-POUND 
FRICE-INCR 

COLLECTIONS: 
SLOOFS (ALSO CURRENT) 

READY DOMAINS: 
YACHTS: RMS INDEXED, PROTECTED READ 


Figure 4-1 (Cont.) Sample Displays Resulting from the SHOW Command 
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4.4 GETTING A COLLECTION TOGETHER -- FIND 


The first step toward manipulating a collection is to "establish" it. 
This process pulls the collection together and gives it an initial 
‘shape or definition. With the three versions of the FIND command 
described in this section, you can choose to: 


e establish a new collection, 
e refine an existing CURRENT collection, or 


@e name and/or sort a collection while establishing it. 


4.4.1 Establishing the Collection 


Before you can perform a number of DATATRIEVE operations, you must 
establish a collection of records for processing. If you wish, this 
collection may consist of all the available records in a domain. Or, 
you may restrict the collection to just a subset of the domain's 
records. You use the FIND command to establish collections. You may 
establish a number of collections in a given DATATRIEVE session 
through multiple usages of the FIND command. The last collection to 
be established is referred to as the CURRENT collection. 


FIND 


Purpose 


Format 


Requirements 


Prompts & 
Responses 


Effects 


Examples 
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This command pulls together or establishes a collection 
of records. This collection may consist of zero, one, 
Or more records. In fact, it may contain all the 
available records. As a result of the FIND command, 
the collection becomes the CURRENT collection. Nothing 
else is done to the resultant collection; it is simply 
formed so that you can perform other operations on it 
such as SELECT, SORT, MODIFY, or PRINT. 


FIND domain-name-1 [WITH condition] 


1. You must supply a domain-name, and it must name a 
domain that you have already readied. 


2. You may optionally wish to restrict the records 
that are collected by specifying the word WITH 
followed by a condition. Section 4.5 provides all 
the rules necessary to formulate this Boolean 
expression. (Observe that a variety of compound 
Boolean expressions are permitted for the 
condition, so that you can effectively specify 
multiple conditions.) 


You must have already performed a successful READY on 
this domain with any of the access modes of READ, 
WRITE, or MODIFY, but not EXTEND. Section 4.1 
describes the READY command. 


No prompting messages appear, but you will be informed 
how many records met your selection criterion. The 
response assumes the following form: 

[nm RECORD(s) FOUND] 


where n is a number representing the number of records 
found. 


1. The records are collected in the order in which 
they are found. You should not infer that there 
will be any order to the collection. 


2. The collection just established by this command is 
now the CURRENT collection. 


3. The collection cursor is left null. 


g example collects all 113 records in the 
Ss 
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DTR>FIND YACHTS; 
[113 RECORDS FOUND] 


The following example illustrates how to collect only 
those-records’ in the domain YACHTS that have an overall 
length that exceeds 32 feet and cost less than $50,000. 


DTR>FIND YACHTS WITH LENGTH-OVER-ALL >32 AND 
DTR>PRICE < 50000 
[36 RECORDS FOUND] 


Note the use of a compound Boolean expression to check 
for two concurrent conditions. 


Also note in this example that the first Ce) follows 
the logical operator AND so that there can be no 
confusion that the command has ended. Only when the 
second Cer) is detected will DATATRIEVE decide that 
the end of the command has been reached. 
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4.4.2 Refining the Collection 


If you have established a collection, but after reviewing it or 
considering the number of records in it, realize you wish to restrict 
it to fewer records, you may want to "refine" it. 


Although you could probably accomplish the same objective by revising 
your last FIND domain WITH condition command, you may want to start 
processing with the collection at hand, instead. This is, of course, 
the CURRENT collection, and it usually represents far fewer records 
than would the whole domain. Thus, time savings are possible when you 
rework an existing collection versus searching the entire domain 
again. The FIND CURRENT WITH condition command does just that. 


Purpose 


Format 


Requirements 


Prompts & 
Responses 


Effects 
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FIND CURRENT 


This command generally applies a restrictive set of 


conditions to the CURRENT collection to produce a new 
CURRENT collection that is more explicitly selected. 
Although the specification of a condition is not 
mandatory, this form of the FIND command has no meaning 
unless a condition is given. 


FIND CURRENT [WITH condition] 


1. You must have established a collection as_ the 
CURRENT collection. 


2. You may optionally wish to restrict the records 
that are collected by specifying the word WITH 
followed by a condition. Section 4.5 provides all 
the rules necessary to formulate this Boolean 
expression. (Observe that a variety of compound 
Boolean expressions are permitted for the condition 
so that you can effectively specify multiple 
conditions.) 


3. If no condition is specified, you have accomplished 
nothing except to make the cursor null since the 
resultant CURRENT collection will b identical to 
the initial one. 


You must have already successfully established a 
collection as the CURRENT collection. 


No prompting messages appear, but you will be informed 
how many records met your selection criterion. The 
response assumes the following form: 

[nm RECORD(s) FOUND] 


where n is a number representing the number of records 
found. 


1. The records are collected in the order in which 
they are found. You should not infer that there 
will be any order to the collection. 


2. The collection just established by this command is 
now the CURRENT collection. 


3. The collection cursor is left null. 


4, The previous collection, unless named, is released. 


Examples 
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The following example assumes you have collected all 
113 records in the domain YACHTS into the CURRENT 
collection and now wish to refine the collection to 
include only those records of yachts manufactured by 
Caribbean. 


DTR>FIND CURRENT WITH BUILDER EQ "CARIBBEAN"; Cer 
[1 RECORD FOUND] 


The following example assumes you have just established 
as the CURRENT collection only those 59 records in the 
domain YACHTS that have an overall length less than 32 
feet and a price less than $50,000. Now you must 
refine that collection to include only those with a 
displacement (weight) less than 7000 pounds. 


DTR>FIND CURRENT WITH DISPLACEMENT < 7000; 
[38 RECORDS FOUND] 
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4.4.3 Naming and Sorting the Collection 


While you frequently use collections as temporary storage and may only 
need -to--use--one- coltection (the CURRENT one) at a time, sometimes” it™ 
is helpful to be able to give a collection a name. Once a_ collection 
carries a name, you can set it aside, establish other collections as 
the CURRENT one, at their separate times, and yet always return to 
process the named collection, when necessary. 


You may also want to sort the collection. Although the SORT command 
described in Section 4.7 does this as its sole function, you may if 
you wish, sort the collection while establishing it. In this most 
powerful version of the FIND command you can establish, name, and sort 
a collection all at once. 


Several points are extremely important regarding named collections: 
e they only exist for your purposes during this session, 
e they cannot be saved, and 
e every type of normal or abnormal exit releases them. 


You need never be concerned that the name you select for your 
collection might duplicate some other user's. Two concurrent users 
can use the same collection name without conflict because collections 
can never be shared. Your only concern should be that if you name 
more than one collection in a session, you might not keep your 
collection names unique. If in doubt, issue a SHOW COLLECTIONS 


command to determine the names you have used. 


Refer to Section 3.7 for the rules for names. 


FIND rse 


Purpose 


Format 


ALL 
FIRST 
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This command gives you the power to establish a 
collection, refine a collection, extract a subset of 
the collection, sort the collection, and/or name a 
collection. If you examine the command syntax 
carefully, you will see that this version of the FIND 
command is actually a superset of the previous two 
versions discussed. All this capability is possible 
through the record-selection-expression, or rse. While 
the rse is fully described in a separate section (see 
Section 4.5), this command offers a practical 
introduction to the key features of the rse. 


FIND record-selection-expression 


where the record-selection-expression (rse) assumes the 
following form: 


CURRENT 
n} [collectn-name-2 IN]( collectn-name-3) [WITH conditn] 
domain-name-1 


[SORTED BY key-1[,key-2...]] 


The record selection expression follows all the rules 
presented in Section 4.5.3. 


1. You must supply either a domain-name, a collection 
name, or CURRENT, and that identifier must pertain 
to a domain that you have already readied. 


2. If you specify FIRST n, n can be any value 
expression that resolves into an integer 
representing the upper bound of the number of 
records found in the domain, CURRENT collection, or 
collectn-name-3. 


3. If you specify the optional ALL, you obtain all 
records in the named collection or domain. 


4. If you specify collectn-name-2, you will give the 
new coliection a name. Be sure the name you assign 
does not conflict with a keyword (Table 3-2) or one 
of the existing names for a defined record, domain, 
or procedure (use SHOW ALL, if necessary to check). 


Requirements 


Effects 


COMMANDS FOR INQUIRY & UPDATE 


5. You may optionally wish to restrict the records 
that are collected by specifying the word WITH 
followed by a condition. Section 4.5 provides all 
the .rules. necessary... to...formulate. this. Boolean. 
expression. (Observe that a variety of compound 
Boolean expressions are permitted for the 
condition, so that you can effectively specify 
multiple conditions.) 


6. The sort-keys assume the following form: 


asc [ENDING] 
DESC[ENDING]| field-name-1 
INCREASING 
DECREASING 


You must have already performed a successful READY on 
the source domain. Section 4.1 describes the READY 
command. 


If you specify CURRENT, there must be an established 
CURRENT collection, formed by a previous FIND command. 


No prompting messages appear, but you will be informed 
how many ‘records met your selection criterion. The 
response assumes the following form: 


[n RECORD(S) FOUND] 


where n is a number representing the number of records 
found. 


1. The records are collected in the order in which 
they are found. You should not infer that there 
will be any order to the collection unless you 
include the optional SORTED BY clause. 


2. If you specify the FIRST n clause, you obtain a 
subset of the collection as the final act after any 
restricting and sorting have occurred. 


3. If the number specified for n in the FIRST n clause 
exceeds the number of records that can be found, 
the maximum will be found. 


Example 


Hint 
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4. The collection just established by this command is 
now the CURRENT collection. 


5. If you specify collectn-name-2, it becomes’ the 
name of the collection you have created. 


6. The collection cursor is left null. 


The following example creates a new collection of ten 
records named the TEN-BEST-BUYS from the domain of 
YACHTS by restricting them to the sloops longer than 28 
feet that weigh at least 7000 pounds and cost up to 
$35,000, It then sorts them into increasing sequence by 
price and skims off the first ten records. 


DTR>FIND FIRST 10 TEN-BEST-BUYS IN YACHTS WITH 
DTR>RIG="SLOOP" AND LOA > 28 AND 
DTR>DISPLACEMENT > 7000 AND PRICE BETWEEN 1 AND C2) 
DTR>35000 SORTED BY INCREASING PRICE; Cer) 

[10 RECORDS FOUND] 


If you use an existing collection name, the existing 
collection is supplanted by the one being established. 
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4.5 RESTRICTING THE SEARCH WITH RECORD SELECTION EXPRESSIONS 


In learning the FIND command in the previous three sections, you 
learned about a syntactical element called a condition. Conditions 
“were used as the selection criteria to” further” definé a group of 
records. Conditions may be expressed in terms of value expressions 
and Boolean expressions. These are important elements in the larger 
structure, the record selection expression. To acquire the background 
to study the full record selection expression, first look at the value 
and Boolean expressions. 


4.5.1 Value Expressions 


The value expression (value~exp) provides an unambiguous 
representation of some combination of items and operators that is 
generally evaluated as a numeric value. Later in this chapter you are 
going to see how value expressions are used in Boolean expressions, in 
the print-list of the PRINT command, in the record number specifier of 
the SELECT command, and in the FIRST n clause of the full record 
selection expression. 


As shown by Table 4-2, the range of items that can be used as value 
expressions is quite large. Table 4-2 summarizes these possibilities 


and explains them. You should be aware that it is possible to create 
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compound value expressions that become quite complex. For example, 
(A + B)/ C * D.+ 500 is a value expression.. 


02-P 


Item Format 


field-name-1 



















collectn-name~-1.field-name-2 


"“character-string" 


integer-1 


- value-exp-1 


( value-exp-2 ) 


value-exp-3 value-exp-4 


NO * Eo + 


Table 4-2 
Value Expressions 


Contents of this field in the CURRENT 
record! are evaluated and used. 


















Contents of this field in the CURRENT 
record! of the named collection are 
evaluated and used. 


The character string is used as given, 
unless the context forces it to be 
treated as a number’. 





A string of digits interpreted as a 
decimal number. 


The resultant value is the negation of 
the value of value-exp-l. 





Causes the evaluation of the enclosed 
value expression to occur prior to 
that of any other value expression 
with which it appears. 






Interpreted as the arithmetic result 
of the operation on the two values ex- 
pressed by the value expressions. 


Remarks 


Uses CURRENT record! of CURRENT collec- 
tion, so both must exist and contain a 
field with this name. 


Be sure to supply a period (.) asa 
connector. The field named must exist 
in the records of the named collection. 
The collection must be established and 
have a CURRENT record?!. 


Any characters may be used except the 
carriage return, line feed, or CTRL Z 
(*Z). To include a quotation mark, use 
two successive quotation marks. 


Take care when using character-strings 
for value-exp-1: they are changed into 
numbers. 


The rules of precedence for arithmetic 
operations hold (unless you use paren- 
theses to force certain operations to 
occur first): multiplications (*) and 
divisions (/) precede additions (+) 
and subtract.ons (-), working left-to- 
right. 


{continued on next page) 
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Table 4-2 (Cont.) 
Value Expressions 


Item Format Description 


value-exp-5 ! value-exp-6 Creates a new character string by com- 
bining the two character strings given 
for value-exp-5 and value-exp-6. 





Special caution should be used with 
numbers. The result maintains a | 
left-to-right pattern. For example, 
"ABC"! "DEF" produces "ABCDEF", 
"12"1"0934" produces "12034", but 
12'034 produces 1234. 
























MAX Computes” your choice of the maximum, 

MIN minimum, average, or total, respective- 
AVERAGE ly of this value expression for all 
TOTAL records (in the CURRENT collection, by 
default). If the OF clause is used, 
then the computation can occur ’on your 
choice of the named collection, the 
named domain, or the CURRENT collection, 
and they can be further restricted by 
the rest of the expression. 


value-exp-7 [OF rse] 





DATATRIEVE-11 prints the message | 
PLEASE SUPPLY VALUE FOR prompt-name~1: 
and waits for your response before it 
processes the command in which this 
value expression occurs. (Examples 
occur in Sections 4.11 and 4.13. 2. ) 


ee iak coker Permits the specification of the value 
Nas boone eonenes i at execution time. Has special impor- 
tance in procedures. Prompt-name-1] 
should be the name you want 
DATATRIEVE-11 to use to prompt you 

to supply a value. 


COUNT [OF rse] Computes the number of records in the 
object of the record selection express- 
ion. 


The default is the number of records 
in the CURRENT collection. 





‘The CURRENT record is the record the collection cursor identifies. The collection cursor can only be moved to 
a record by the SELECT command, which is discussed in Section 4.6. 


value expressions are treated as numbers in the SELECT command, in the FIRST n clause of the record selection 
expression, and when subject to arithmetic operators (+, -, *, and /) or computations for maximum, minimu 
total, and average. Thus, these are not appropriate places for the alphanumeric character string. 
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4.5.2 Boolean Expressions 


Boolean expressions describe conditions used to restrict a collection 
to records that satisfy these criteria. The Boolean expressions may 
be simple (used alone) or compound (combined with other Boolean 
expressions). When they are incorporated in commands, DATATRIEVE 
always tests to see whether they are true for a given record. If the 
expressions are true, DATATRIEVE performs the command function on the 
record. If the expressions are not true, the record is rejected by 
the command. 


Simple Boolean expressions compare the value of a particular field in 
a record against specified values. The comparison is based on certain 
"operators" that are shown in the formats summarized in Table 4-3. 
Note that some operators are synonymous; choose the one you like the 
best. 


Compound Boolean expressions combine two or more Boolean expressions 
to create a more precise definition of the conditions to apply. The 
compound Boolean expressions are given in the second half of fable 
4-3. 


r~ 
I 


Ee 


Table 4-3 
Boolean Expressions 


Operator 
Symbol Format/Example . 



















Meaning 
> > B True if A is greater than B 
GT GT B 
GREATER-THAN GREATER-THAN B 
GE GE B True if A is greater than or equal to B 
GREATER-EQUAL GREATER~EQUAL B 
< < B True if A is less than B 
LT LT B 
LESS~-THAN LESS-THAN B 
LE LE B True if A is less than or equal in value to B 
LESS-EQUAL LESS-EQUAL B 
EQ EQ B True if A equals B 
EQUAL EQUAL B 
= = B 
EQ B,C, [OR] D True if A equals any of the three values, B, C, or D 
EQUAL B,C, [OR] D 
= B,C, [OR] D 
NOT-EQUAL NOT-EQUAL B True if A does not equal B 
NE NE B 
BT BT B [AND] C True if the value of A falls in between the range of values of B thrdugh 
BETWEEN BETWEEN B [AND] C C, inclusive | 
BOOL-A AND BOOL-B True if the values of the Boolean expressions BOOL-A and BOOL-B are hoth 
PRICE>10000 AND C2r) true 
BUILDER EQ "SEAWORTHY" 
NOT BOOL-A_. True if the value of the Boolean expression BOOL-A is false 
NOT PRICE>10000 Caer) 
BOOL-A OR BOOL-B True if either of the Boolean expressions BOOL-A or BOOL-B is true 
-MODEL="43K" OR MODEL="49K" 
(BOOL-A) True if BOOL-A is true. The parentheses force the evaluation of this 


Boolean first. Note that BOOL-A can be a compound Boolean, and this:is a 
Means of grouping: Booleans in case the normal precedence rules* would not 
produce the desired effect. 


(BEAM<12 AND LOA BT 20 AND 35) 


Note : 
The character A above represents a field name, while B, C, and D are value expressions (as described in Section 4.5. 1). 


*Normal precedence rules require evaluation of expressions with NOT zaneh followed by expressions with AND, followed by 
expressions with OR. 
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4.5.3 Full Record Selection Expressions 


The full record selection expression (rse) combines a number of 
elements already learned, including value expressions and Boolean 
expressions, as well as a sorting clause. It is a very powerful 
subexpression in a number of commands and as such will be described in 
much the same way the commands are. 


Purpose 
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rse 


This subexpression specifies a collection of records. 


Format 


ALL 
FIRST n 


CURRENT 
[collectn-name-2 IN]( collectn-name-3) [WITH conditn] 
domain-name-1 


[SORTED BY key-1[,key-2...]] 


1. 


You must supply either a domain-name, a collection 
name, or CURRENT and your choice must refer to a 
source domain that you have already readied. 


If you specify FIRST n, n can be any value 
expression that yields an integer representing the 
upper bound of the number of records desired for 
processing. 


If you specify ALL, all records in the named domain 
or collection will be processed. This is also the 
default. 


If you specify collectn-name-2, you will create a 
new collection name. The only case where this 
collection name is retained, however, is when the 
rse occurs in a FIND rse command. When the rse 
occurs in a MODIFY or PRINT command, the new 
collection name is lost when the command completes. 
Be sure the name you assign does not conflict with 
a keyword (Table 3-2) or one of the existing names 
for a defined record, domain, or procedure (use 
SHOW ALL, if necessary, to check existing names). 


You may optionally wish to restrict the records 
that are collected by specifying the word WITH 
followed by a condition (Boolean expression). 
Section 4.5.2 provides all the rules necessary to 
formulate this Boolean expression. 


If you specify the SORTED clause, the sort occurs 
on either the CURRENT collection, the domain, or 
collectn-name-3. 


The sort-keys assume the following format: 


asc [ENDING] 
DESC [ENDING] | field-name-1 
INCREASING 
DECREASING 


The number of sort-keys you may specify is 
unlimited. If you exceed the system capacity, you 
will be notified that the dynamic memory is 
exhausted. 


The specification of the word BY is optional, and 
is only offered to maintain an English-like 
structure. 


Requirements 


Prompts & 
Responses 


Effects 
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10. Every field-name specified as a sort-key must be 
legal for the CURRENT collection. This means the 
field must occur in the record definition. 


ll. If the specifications of ASCENDING, INCREASING, 
DESCENDING, or DECREASING are omitted for the first 
sort-key, DATATRIEVE assumes you wish this field 
sorted in ASCENDING sequence. 


12. If the sort direction specification is omitted on 
subsequent sort-keys, DATATRIEVE assumes you want 
the last-specified sorting-direction to prevail. 


13. When more than one field-name is specified, the 
collection is sorted so that the first field-name 
is treated as the major sort key, and each 
successive key becomes more and more minor. 


If you specify CURRENT, there must be an established 
CURRENT collection. If you name a collection for 
collectn-name-3, that named collection must be 
established. 


No prompting messages appear, unless you introduced a 
value expression of the form 


* ,prompt-name-1 


1. The collection of records is formed in the order in 
which the records are found. You should not infer 
that there will be any order to the collection 
unless you include the optional SORTED BY clause. 


2. If you specified the FIRST n clause, you obtain a 
subset of the collection as the final act after any 
restricting and sorting have occurred. 


3. If the number specified for n in the FIRST n clause 
exceeds the number of records that can be processed 
to meet the selection criteria, the maximum number 
will be chosen. 


4. The collection cursor is left null. 
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If all the elements in the expression are 
specified, the sequence of events is as follows: 


a. Restrict the collection according to the WITH 
clause. 


b. Sort the collection per the SORTED BY 
specifications. 


c. Extract the FIRST n of the results. 


dad. Name this collection according to collectn- 
name-2. 


If a given rse omits any of the clauses, that 
particular step disappears, but the progressive 
sequence still follows as above. 
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4.6 SELECTING A PARTICULAR RECORD IN A COLLECTION -- SELECT 


Once you have established a collection, the ability to manipulate the 
collection cursor through the established collection becomes a prime 
consideration. The SELECT command provides this capability. 


Purpose 


Format 


Requirements 


Restriction 


Prompts & 
Responses 


Effects 
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SELECT 


This command specifies that you want a particular 
record made available for your purposes from either the 
CURRENT collection or a named collection. You succeed 
in moving the collection cursor to a particular point 
in the collection. The record you move to becomes’ the 
CURRENT record, and the one immediately after it 
becomes the NEXT record. Remember, a record may be the 
CURRENT record without necessarily being in the 
collection that is the CURRENT collection. 


FIRST 
NEXT 

SELECT LAST [collectn-name-1] 
value-exp-1l 





1. You should supply a record number specifier such as 
FIRST or LAST. If you omit this specifier, it is 
assumed that you wish the NEXT record in the 
collection. 


2. The specification for value-exp-l must be a value 
expression that produces a positive integer, and it 
Must not exceed the total number of records in the 
collection. This restriction prohibits the use of 
alphabetic character strings and necessitates 
caution with alphanumeric character strings. 


3. You may optionally wish to use collectn-name-1l to 
name a specific collection for the selection 
process; otherwise, it is assumed you wish to 
reference the CURRENT collection. 


You must have already established either the named 
collection or a CURRENT collection. 


You should not use the SELECT command in any compound 
statements. Compound statements are created with the 
statements in Section 4.13. 


None. 


The effects of the command are highly dependent on the 
record number specifier given and the state of the 
collection and the position of its cursor at the 
outset. Table 4-4 summarizes the different effects. 


Notice particularly that any time you attempt a SELECT 
on an empty collection, you will get an error message. 


Examples 


Hints 
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Because there can be multiple collection cursors, 
SELECTing a record from a collection does not make that 
collection CURRENT if it was not already so. 


The following example shows two ways to select the very 
next record from the CURRENT collection. 


DTR>SELECT NEXT; (1) 
DTR> SELECT; (2) 


In Method (2), the record number specifier was omitted 
and NEXT is used by default. 


The following example illustrates how to select just 
the first record from the collection of small boats 
(less than 26 feet long). 


DTR>SELECT FIRST SMALL-BOATS; 


This example illustrates how to select the twentieth 
yacht record in the collection of medium-sized yachts. 


DTR>SELECT 20 MEDIUM-YACHTS; 


This example selects the last yacht record in the 
CURRENT collection. 


DTR>SELECT LAST; 


It is important to keep track of which collection is 
the CURRENT collection in case you want to omit the 
collection name in the SELECT command or others. If 
you have any doubts about which collection is current, 
you can always issue the SHOW CURRENT command. (See 
Section 4.3.) 


When the collection cursor is null, the use of a SELECT 
NEXT command is equivalent in effect to a SELECT FIRST. 


4-34 
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Table 4-4 
Effects of the SELECT Command 









Specifi- 
cation 










Normal Effect Empty Collection Cursor at LAST 


















FIRST Cursor points Cursor is null Gets first member 
to first member (Error) with no error 
NEXT Cursor advances Cursor is 
forward one unchanged, error 
record message is given 
LAST Cursor points Cursor is 
to last member unchanged 
value-exp-1 | Cursor moves Gets the 
to member value-exp-1 
numbered member, if it 







value-exp-1 exists, no error 
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4.7 PUTTING RECORDS INTO AN ORDER ~- SORT 


You will find frequent need to order or reorder collections of 
records. The sorting facility supplied by the SORT command alone or 
the SORTED BY clause in other commands gives you this power. 
Collections can be sorted into ascending (increasing) or descending 
(decreasing) sequence based on the standard ASCII collating sequence. 


Purpose 


Format 


Requirements 
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SORT 


collection of records. You may decide you wish the 
collection ordered according to certain key data fields 
and each of these fields can be in either ascending or 
descending order. 


SORT [collection-name-1] BY sort-key-1 [,sort-key-2...] 
where each sort-key assumes the following form: 


ASC [ENDING] 
DESC[ENDING]| field-name-1 
INCREASING 
DECREASING 


1. If you omit a collection-name, it is assumed that 
you want the sort to occur on the CURRENT 


collection. 
2. If you provide a collection-name, it must be the 
name of an established collecti on 


3. The number of sort-keys you may specify is 
unlimited. If you exceed the system capacity, you 
will be notified that the dynamic memory is 
exhausted, 


4. The specification of the word BY is optional, and 
is only offered to maintain an English-like 
structure. 


5. Every field-name specified must be legal for the 
collection being processed. This means it must 
occur in the record definition. 


6. If the specifications of ASCENDING, INCREASING, 
DESCENDING, or DECREASING are omitted for the first 
sort-key, DATATRIEVE assumes you want this field 
sorted in ASCENDING sequence. 


7. j%&.If the sort direction specification is omitted on 
subsequent sort-keys, DATATRIEVE aSsumes you want 
the last-specified sorting-direction to prevail. 


8. When more than one field-name is specified, the 
collection is sorted so that the first field-name 
is treated as the major sort key, and each 
successive key becomes more and more minor. 


You must have already performed a successful FIND on 
this collection. Section 4.4 describes the FIND 
command. 


Prompts & 
Responses 


Effects 


Examples 


Hints 
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None. 


1. The records in the collection are sorted into the 
order specified or implied. 


2. The collection cursor is null at the conclusion of 
this command. 


3. Any remaining pointers’ to records previously 
removed by an ERASE command (Section 4.10) are 
permanently erased. 


The following example sorts all the yacht records in 
the 26-foot yacht collection into alphabetical order 
based on the manufacturer name first and then on _ the 
model number. 


DTR>SORT YACHTS-26 BY ASC MANUFACTURER, MODEL; 


The following example illustrates how to sort the 
records in the CURRENT collection into order according 
to the yachts having the highest price. 


DTR>SORT BY DESCENDING PRICE; Cer) 


If you encounter a problem in sorting, most likely it 
will be in exceeding the memory space. If this should 
happen, you may want to consider any or all of the 
following approaches: 


1. FINISH any domains you can (Section 4.12.2). 


2. RELEASE any collections you won't need (Section 
4.12.1). 


3. READY domains that were readied for WRITE or MODIFY 
access to permit read-only access since this mode 
uses less buffer space (Section 4.1). 
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4.8 LOOKING AT THE RECORD CONTENTS -~ PRINT 


By this time, the beginning user who used a terminal to practice the 
preceding commands is probably frustrated by being unable to "look at" 


the results of the commands entered. The PRINT command permits you to 
display certain parts of the collections. 
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PRINT 


4.8.1 Listing Record Contents 


Purpose 
This command provides a printout of the record 
contents. You may request to see one or more fields in 
either a single record or a complete collection of 
records. Since these printouts can be formatted to a 
certain extent, they are quite sufficient for informal 
purposes. However, you may want to consider’ the 
capabilities of the Report Writer for more elaborately 
formatted printouts. See Chapter 5 for a discussion of 
the Report Writer. 

Format 


: . file-spec-l 
PRI r - - 
nT [ALL] [print-list-1] [oF rse]) [on rtie-seecnt }) 
where the record-selection-expression (rse) assumes the 
following form: 


ALL CURRENT 
FIRST n|[collectn-name-2 IN]< collectn-name-3\[WITH conditn] 
domain-name-1l 


(SORTED BY key-1[,key-2...]] 


If necessary, review the descriptions of record 
selection expressions in Section 4.5.3. 


1. If you specify ALL before the print-list, you will 
obtain a printout of all the records in the group 
you designate. 


2. If you omit ALL, the printout will include only the 
items desicnated for the CURRENT record of the 
designated group. 


3. The optional print-list can specify names, value 
expressions, literals, and horizontal and vertical 
spacing characters. The print-list assumes' the 
form of any combination of the optional elements 
shown in Table 4-5. Print-list elements. are 
separated by commas. Note that "n" (as shown in 
the table) represents a decimal integer of your 
selection. For more details see Section 4.8.2. 


4, The optional OF rse clause refers to the same 
record selection expression seen in Section 4.5.3. 
This powerful expression lets you print records 
from named collections rather than restricting you 
to the CURRENT coilection and permits sorting them, 
refining them, and/or even subsetting them -- all 
in one command. If the OF rse clause is used, it 
completely overrides the specification of ALL. 


5. If you specify the optional ON file-spec-l clause, 
file-spec-l must be the name of a file or device 
specification. If you omit the file specification, 


Requirements 


Prompts & 
Responses. 


Effects 


Examples 


Hints 
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the printout appears on your terminal device. Note 
your other alternative is to use the 
value expression * ,prompt-name (described in 
Section 4.5.1) to prompt a later entry of a file or 
device specification. 


Note that all the command elements after the 
command name PRINT are apparently optional. It is 
fine to specify only the word PRINT if the CURRENT 
collection has a CURRENT record; you will get the 
printout for that one record. However, if there is 
no CURRENT record in the CURRENT collection and if 
you omit all the optional command elements, you 
will obtain an error message anda printout of 
every field in every record in the CURRENT record 
collection. 


Again, be warned that all optional command 
elements, if specified, must be given in the 
sequence shown. 


The collection cursor must not be null or else you must 
request ALL. 


No prompting messages appear. 


The printout will conform to the examples provided 
in Pigure 4-1. Note that the default column 
headers consist of the field-names as specified in 
the record definition. 


The output of the command is directed to the 
terminal device, unless you provide an alternate 
file specification with the ON file-spec-l clause. 


The values of the fields are printed in the 
appropriate columns. 


The collection cursor is left unchanged. 


More examples occur in Figure 4-2. 


You 


May wish to use the CTRL O (“O) character 


combination to halt a lengthy printout that you realize 
is in error or should not have started at this time. 


If a printout is moving over your video terminal screen 
faster than you can read it, you may want to use the 
CTRL S (“S) to cause a temporary interruption and _ the 
CTRL Q ("Q) to resume. However, a better choice may be 
to direct the printout to another file for hard copy 
review. 
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You may abbreviate the PRINT command in just ' two 
possible ways. You can eliminate the words ALL and OF 
when. you have no print-list, want ALL records, and want 
to specify either a domain name or FIRST n. Thus, the 
following exceptions to the syntax above will be 
accepted: 


DTR>PRINT FIRST 5 MEDIUM-YACHTS WITH PRICE > 5000; 


DTR>PRINT YACHTS WITH PRICE<100000 SORTED BY DESC PRICE; 


Cv-P 


pment 


field-name-1 [modifiers] 









value-exp-1 [modifiers] 










SPACE [n] 


TAB [n] 
















SKIP [n] 











Table 4-5 
Print-list Elements 








Function 





Specifies a class of data 


items to be printed 
from the record. 
Modifiers are 
explained below. 


A value to be in- 
serted. (See Section 
4.5.1.) Modifiers 
are explained below. 


Causes n horizontal 
Spaces between entries 
on each line. 


Introduces as many 

tab characters into the 
print line as: spec- 
ified by n. 


Advances across the 
horizontal line to col- 
umn n. Notes: n must 

not be less than 1 or 
more than the. page 
width. If n is less 
than present column, a 
line is skipped. 


Moves n blank lines 
ahead to start a new 
line. Printing starts in 
column 1, unless another 
element modifies the 
position further. 





Default 


All the fields 
in the record 









1 space 












If n is omitted, a 
Single tab is assumed 
















Single spacing 









(continued on next page) 


aLVddN % AYINONI YOdI SANWWNOD 


vv-? 








Element 


NEW--PAGE 


("header-1" [/"header-2"...]) 


USING edit-string 


Table 4-5 (Cont.) 
Print-list Elements 


Function Default 






Begins a new print 
page. Printing starts in 
column 1, unless another 
element modifies the 

position further. 








Specifies a character- Headers are composed 
string (Section 3.8) of the field-name 

to be printed on definitions from the 
successive lines over record definitions 
the immediately preceding 

field-name or value-expression. 

Specification of a 

hyphen for the header 

indicates no header is 

desired. 


Uses the edit-string in 
the record definition, if 


Imposes the character- 
istics of this edit- 
string on the preceding any. Otherwise consid- 


field or value expression. ers the field's PICTURE 
Edit-strings must observe string. 
COBOL rules (Appendix E). 





NOTE 


DATATRIEVE-11 restricts the column width to 132 characters. It 
automatically sets tabs at every eighth column. Thus, if the print 
position is column 10 and DATATRIEVE encounters a TAB 2 specification, the 
new position will be column 24. 





aLVddN ¥ AWINONI YOdA SANVWWOD 
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4.8.2 Formatting the Printout . 


In the description of the PRINT command you learned that you could 
Specify.._aprint-list.Table 4-5..summarizes-the—possible-elements- you 
may choose for your print list. These elements may be mixed in many 
combinations. All are optional. Sometimes DATATRIEVE assumes a 
default value when you omit an element in the print list. Print-—lists 
are processed in left-to-right order. 


Figure 4-2 provides some examples of the PRINT command and the actual 
printouts that were produced from them. 





UTR>!SET UF FOR A DEMONSTRATION OF VARIOUS FORMS OF THE PRINT COMMAND 
UTR>READY YACHTS SHARED REAL 

DTR>FIND YACHTS WITH RIG="SLOOP* AND PRICE#20000 SORTED BY LOA} 

C8 RECORDS FOUND 

UTR>SELECT 43 

DTR> | 

TTR Dd OOO OOOO OO GOGO OGIO IK 

DTR>!FRINT ALL THE FIELDS OF JUST THE 4TH RECORD OF THE CURRENT COLLECTION 
DTR>!0F SLOOPS FRICED OVER $20,000 

DTR>!(IT’S THE SELECTED RECORD) 


DTR> | 
DTR>PRINT 
LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
BAYFIELD 30/32 SLOOF 32 97500 10 $327875 


DIT RO UO OOOO OOO IO IO OOK OKI IK 

DTR>!THE NEXT 3 EXAMPLES JUST PRINT THE VALUE EXPRESSIONS IN THEIR PRINT-LISTS 
DTR>! 

DTR>PRINT "DATATRIEVE-11 MAKES":" REFORT WRITING ‘» "EASY" 

DATATRIEVE-11 MAKES REFORT WRITING EASY 


DTR>PRINT "2 + 2 = 5° 
24225 


DNTRSPRINT 2+2 
4 


TTR FOO OOOO ORO AK AK OK AK 

DTR>! PRINT THE MANUFACTURER AND MODEL FIELDS OF ALL THE RECORDS IN THE CURRENT 
DTR> |! COLLECTION 

DTR>! 

DTRSFRINT ALL COL 10»MANUFACTURER?COL 30»MODEL? 


MANUFACTURER MODEL 


CAFE DORY 28 

SABRE 28 

RYLER S. CROSS 
BAYFIELD 30/32 
CHALLENGER 32 
CARIBBEAN 35 
CHALLENGER 35 
CHRIS-CRAF CARI BREAN 





Figure 4-2 Sample PRINT Command Output 
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DT? aa OOO GOOG COCO OIC OK 
DTR? IPRINT ALL FIELDS OF ALL KETCHES PRICED OVER $30%000r 
UTR? 1SORTED BY LENGTH 


DTR> 1 
DTR* PRINT YACHTS WITH RIG = "KETCH" AND FRICE » 30000 SORTED BY LOA 
LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
I. TRADER 37 KETCH 36 18600 12 39500 
ALBERG 37 MK II KETCH 37 209000 12 $36%951 
IRWIN 37 MARK II KETCH 37 202000 11 $36%950 


HEPES CCC SSS SCC SS CESSES SOS SOSS CSCC OSS SSS STS SSH 

Bray ERENT ALL FIELDS OF ALL RECORDS IN THE DOMAIN OF YACHTS 
> 

DTR> PRINT YACHTS 


LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
ALBERG 37 MK II KETCH 37 202000 12 $369951 
ALBIN 79 SLOOP 26 42200 10 $17%900 
ALBIN VEGA SLOOP 27 52070 O08 187600 
AMERICAN 26 SLOOF 26 4000 08 $9 9895 
AMERICAN 26-MS M/S 26 39500 O08 $189895 
BAYFIELD 30/32 SLOOP 32 99500 10 $329875 
CAFE DORY 28 SLOOP 28 97000 OF 219790 
CAFE DORY TYFHOON SLOOP 19 12900 06 $4295 
CAPE DORY 25 SLOOP 25 42000 07 $8 2995 
CARIBBEAN 35 SLOOP 35 18000 11 $37%7850 
CHALLENGER 32 SLOOP 32 129800 11 $31,835 
CHALLENGER 35 SLOOP 35 149800 12 $39r215 
CHRIS-CRAF CARIBBEAN SLOOP 35 182000 1t1 37850 
CLIPPER CM 30 SLOOP 30 3800 08 $9 9500 
CLIPPER “CM 32 SLOOF 32 42500. 08 $127950 
EASTWARD HO M/S 24 72000 QF 157900 
GRAMPIAN 26 SLOOP 26 37600 O08 $119495 
GRAMPTAN 28 SLOOP 28 69900 10 $14%475 
GRAMPIAN 34 KETCH 33 127000 10 $297675 
HUNTER 27 SLOOP 27 69500 OF $147999 
I. TRADER 37 KETCH 36 182600 12 $39%500 
IRWIN 37 MARK II KETCH 37 207000 11 $36%950 
IRWIN 235 SLOOF 25 97400 12 $10%950 
ISLANDER 28 SLOOP 28 329994 10 $159908 
ISLANDER BAHAMA SLOOP 24 4200 08 $6 7500 
LINDSEY 39 M/S 39 142500 12 $35»900 
RYDER S. CROSS SLOOF 31 13%4600 00 $32%500 
SABRE 28 SLOOF 28 727400 OF $22%000 
SALT 19 SLOOP 295 29600 07 $69590 
TANZER 26 SLOOP 26 49350 O09 #119750 
TANZER 28 SLOOF 2s 69800 10 175500 
VENTURE 21 SLOOF 21 12500 07 $2823 
VENTURE 222 SLOOF 22 22900 07 $3564 


WESTERLY CENTAUR SLOOF 69700 $157245 





Figure 4-2 (Cont.) Sample PRINT Command Output 
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TTR Hg OOOO OO OOO OOOO OOK I KOK 

DIR? 1 PRINT ALL THE FIELDS OF THE FIRST 3 RECORDS IN THE GROUF OF YACHTS THAT ARE 
OT ES SHORTER THAN 26 FT. 

i 


-DTR? PRINT-FIRST 3 SMALL=YACHTS IN YACHTS WITH LOA < 26 


LENGTH 
OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM FRICE 


CAPE DORY TYFHOON SLOOF 19 1%900 06 $49295 
CAFE DORY 25 SLOOP 25 47000 07 $89995 
EASTWARD HO M/S 24 77000 O09 $15%900 


TRO Gadd OOOOO OOOO OOOO OCG O GOO IOG KOK 

DTR> iPRINT JUST THE FRICE FOR THE SAME GROUP BUT EDIT IT DIFFERENTLY 

DTR> | 

DTR> PRINT FRICE USING $ZZ?ZZZ.00 OF FIRST 3 SMALL-YACHTS IN YACHTS WITH LOA : 


PRICE 
$ 49295.00 


$ 89995.00 
$15»900.00 





TTR? a OOOO OOOO IORI IO OK OK a OK 


DTR? PRINT THE CURRENTLY SELECTED RECORD IN THE CURRENT COLLECTION 
DTR> | 


DTR> PRINT 

LENGTH 

OVER 
MANUFACTURER MODEL RIG ALL WEIGHT BEAM PRICE 
BAYFIELD 30/32 SLOOP 32 99500 10 $32/875 


UTR? iWERE YOU SURFRISEL? NONE OF THE FRINT COMMANIS HAVE REALLY ESTABLISHED 
DTR> 1COLLECTIONS OR SELECTED ANY RECORDS» SO THE CURRENT RECORD IS STILL THE 4TH 
UTR? 1RECORD IN THE COLLECTION OF SLOOFS FORMED BY THE VERY FIRST 3 COMMANIS 
BTR? i OOOO OOO OOO GOO OK 

QTR> te RINT THE PRICE: MANUFACTURER ANI MODEL OF YACHTS COSTING OVER 

OTR> 1$35,000. DOUBLE SFACE THE FRINTOUT. “START IN COLUMN 16% GIVING 
OTR? i THE PRICE FIELD THE HEADING “IT’S ONLY MONEY". FRICE WILL BE 

OTR? |ZERO SUPFRESSED», BUT NO DOLLAR SIGN IS DESIRED. 

TRE | 

UTR> PRINT SKIF 2yTAB 2sFRICE(*IT’S ONLY"/"MONEY") USING - 

DTR> 77»7ZZ» COL 34yMANUFACTURER» MODEL OF YACHTS WITH - 

OTR? PRICE2350003 


IT’S ONLY 
MONEY MANUFACTURER MODEL 


369951 ALBERG 37 MK IT 


37850 CARIBBEAN 35 


397215 CHALLENGER 35 





Figure 4-2 (Cont.) Sample PRINT Command Output 
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4.9 CHANGING RECORD CONTENTS IN THE FILES -- MODIFY 


One of the most powerful capabilities of DATATRIEVE is the ability to 
change the data as it exists in the RMS-1l files. With all the 
commands previously described, all actions occurred on copies of 
portions of the files. At no time were you able to affect the file 
itself. However, with the MODIFY command, you will be able to change 
data values in specific records. Certain safeguards are, however, 
inherent in the system. For example, you will only be able to use the 
MODIFY command on domains you successfully readied in WRITE or MODIFY 
mode. (See Section 4.1.) 


Purpose 


Format 


Requirements 


Restriction 
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MODIFY 


This command can change from one to all the data fields 
in: 


@e any given record or 


e all the records in a collection. 


MoDIFy [ALL] [fld-name-1 [,fld-name-2...]] [oF rse] 


where the record selection expression (rse) assumes the 
form: 


CURRENT 


A 
bes n [collectn- name-2 IN]{ collectn-name-3) [WITH conditn] 


domain-name-1l 


[SORTED BY key-1[,key-2 


If necessary, review the descriptions of record 
selection expressions (Section 4.5.3) and sort-keys 
(Section 4.7). 


1. If you specify ALL before fld-name-1, then the 
changes you request will be made to every record in 
the group you designate. If you omit ALL before 
fld-name-l, then your changes will be made only to 
the CURRENT record in either the named or CURRENT 
collection. 


2. If you supply a field name, it must name aé_ field 
that belongs to the record type associated with 
either the CURRENT or named collection. 


3. If you omit the field names, DATATRIEVE will prompt 
you to specify a change value for every field in 
the record. 


You must have already performed a successful READY on 
the source domain for the records, and it must be 
readied for WRITE or MODIFY access. Section 4.1 
describes the READY command. 


Unless you are specifying ALL, the collection cursor 
Must not be null; it must point to a record as the 
result of a successful SELECT command. Section 4.6 
describes the SELECT command. 


You cannot modify the primary key field in any indexed 
sequential record. 
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Prompts & 
Responses 


Effects 


Example 


Hints 
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Once your command has been accepted, DATATRIEVE prompts 
you with a request to specify the new value for each of 
the field names. If all field names are being changed, 
then they will be requested in the order of the record 
definition. 


DATATRIEVE prompts with the message 
PLEASE SUPPLY VALUE FOR field-name: 


It then waits for you to enter a value after the colon. 
Note that DATATRIEVE prompts for each elementary data 
item in the field names you supplied, or issues all the 
field names one-by-one. 


If at any time in the prompting cycle, you want to 
escape, you can enter a CTRL Z (2). This aborts the 
MODIFY command, and prints the message 


EXECUTION TERMINATED BY OPERATOR 


1. In both the collection and the RMS-11l file each 
field name specified is changed to the new value 
supplied. 


2. The collection cursor is left unchanged. 


3. Additional effects may occur as prescribed by the 
record selection expression. (See Section 4.5). 


The following example changes two fields in the four 
records in the collection of yachts built by Seaworthy. 


DTR>MODIFY ALL DISP, PRICE OF SEAWORTHY-YACHTS; 
PLEASE SUPPLY VALUE FOR DISP: 5500 C=) 


PLEASE SUPPLY VALUE FOR PRICE: 22500 


The values supplied should correspond to the data 
characteristics established for the field in-the record 
definition. For example, the field length of’ the new 
value should not exceed the defined length. Explicit 
checking is not performed, but certain violations will 
be recognized if DATATRIEVE uncovers an incompatibility 
while moving the new data into the area reserved for 
the old data. 


You will not be permitted to skip over a data item by 
responding with just a carriage return ((C#)). If you 
do, you will be prompted again to supply the same 
field. However, you can leave a data item empty or 
zero-~valued by entering a single space before the 
carriage return. 
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4.10 REMOVING ONE OR MORE RECORDS -- ERASE 


During routine operations, it is not uncommon to determine that one or 


more records are invalid or have outlived their usefulness and should .... 


be removed from a file. This sort of file maintenance function is 
generally performed by a program at the installation. However, 
DATATRIEVE-11 offers the ability to perform "simple" removals of 
certain records. However, the word "simple" is critical here. When a 
record is removed by DATATRIEVE, there is no audit trail left. 
Because no historical details from the record are retained, serious 
accounting problems can result if ERASE is used indiscriminately. 
This is one reason why the use of passwords and access modes is so 
important. However, abuses can still occur at the hands of qualified 
users. Hopefully, when you use the ERASE command, you will do so with 
the proper amount of caution and respect for the data integrity. 
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ERASE 


Purpose 
This command removes one or more records from the 
files. 

Format 

ERASE [ALL [OF rse]] 

where the record-selection-expression (rse) assumes the 

following form: 

ALL | CURRENT 
FIRST n|[collectn-name-2 IN] collectn-name-3} [WITH conditn] 
domain-name-1 

[SORTED BY key-1[,key-2...]] 

If necessary, review the descriptions of record 

selection expressions (Section 4.5.3) and sort-keys 

(Section 4.7). 

1. If you supply a record selection expression, it 
must refer to a collection in a source domain that 
you have already readied in WRITE access mode. 

Requirements 

You must have already peformed a successful READY on 

the source domain for WRITE access. Section 4.1 

describes the READY command. 

Restriction 
You cannot erase sequential RMS-1l records. 
Prompts & 
Responses 
None. 
Effects 

1. If you omit the optional elements, you will erase 
only the CURRENT record of the CURRENT collection, 
if any. 

2. If you specify only ALL, you will erase every 
member of the CURRENT collection. 

3. I£ you specify the optional rse, you will erase 
every record of the collection you identify. 

4. The collection cursor becomes null. 

Examples 


The following example illustrates how you could erase 
all records in the CURRENT collection. 


mAmpoyPRAGD ATT.» fan \ 
DIK Gane Airy RT 


Hints 
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The next example illustrates how you could erase just 
the CURRENT record in the CURRENT collection. 


DTR>ERASE; (er ) 


The last example illustrates how to erase all the 
records in the named collection SMALL-BOATS. 


DTR>ERASE ALL OF SMALL-BOATS; CC®) 


You must know which is the CURRENT collection and which 
is the CURRENT record before you attempt any ERASE 
command. If in doubt, use the SHOW CURRENT command 
(Section 4.3) and/or the PRINT command (Section 4.8) to 
ensure that you know what you will be erasing. 


If you request a printout that includes erased records, 
DATATRIEVE omits the deleted records. However, if you 
SELECT a record that has been erased, DATATRIEVE 
notifies you that the record has been removed. This 
notification is possible since a record pointer remains 
after the deletion occurs. 


Tt is only through the SORT command or SORTED BY clause 
(Sections 4.7 and 4.4, respectively) that pointers to 
records previously erased are removed. 
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4.11 ADDING A NEW RECORD TO THE FILE -- STORE 


Certain qualified users may be permitted to add new records to 
existing files. This is a common file maintenance function in any 
installation, but there are some advantages (with attendant 
disadvantages) to using DATATRIEVE for this function. The DATATRIEVE 
user can rapidly add a record and supply data for the fields, avoiding 
the need to use a special file maintenance program. However, opening 
records with DATATRIEVE includes the risk that correct procedures may 
not be followed. Furthermore, data will not be subjected to extensive 
edits and logical crosschecks such as a specialized program could 
impose. For example, if it is known that sailboats can only have 
lengths between 8 and 70 feet, you would logically assume an error has 
been made if someone specifies 2 or 99 feet for the LOA 
(length-over-all field). This is the sort of checking a_ specialized 
program could do that the more casual DATATRIEVE user could omit. 


Likewise, suppose management has recently dictated that no more boats 
Manufactured by SMITT-JONES should be accepted. Now, even if the 
maintenance program has been updated to include a test for this 
prohibition, the unwitting DATATRIEVE user could insert new records 
and undermine the policy decision. 


Using DATATRIEVE to add records to files is the quick and dirty 
method, in every sense of the expression. Please be aware of the 
potential problems that this feature can cause. 


Purpose 


Format 
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STORE 


This command créatés a new réecorad “in “the domain ~ you 
specify. DATATRIEVE accepts your specification of the 
fields you want to enter or prompts you to specify data 
for each field defined for the record. 


STORE domain-name-1 [USING statement-1] [VERIFY USING statement-2] 


Requirements 


Restriction 


Prompts & 
Responses 


1. You must supply a domain-name, and it must name a 
domain you have already readied for WRITE or EXTEND 
access (Section 4.1). 


2. If you want to provide a statement for statement-l, 
in general it will assume the following form: 


BEGIN fld-name-1l = value-l 
;£ld-name-2 = value-2...] 





> END 
where its keyword USING, if specified, must be on 
tha eama linn aac tha beuwood STORE; tha ramainina 
LLlinw nw? At wa hdd an wrt ae he a ww With wesiwN os emaining 
elements, separated by semicolons, may be on one or 
more successive lines. . Follow the usual 


conventions regarding hyphens and carriage returns 
for line continuations. You may want to read about 
the BEGIN-END Block and assignment statements that 
are described in Section 4.13. 


3. If you specify a VERIFY clause, no data is_ stored 
until the conditions of statement-2 are completed. 
Thus, this provides an opportunity to ensure that 
data is correct before it becomes part of the file. 


4. The optional word USING is permitted for 
English-like usage, but serves no other purpose. 


You must have already performed a successful READY on 
this domain for either WRITE or EXTEND access. Section 
4.1 describes the READY command. 


You cannot STORE new records into RMS-ll relative 
files. 


Unless you specify a statement giving field-names' and 
desired values, you will be prompted to supply data for 
each of the defined fields in the _ record. The 
prompting message assumes the following form: 


PLEASE SUPPLY VALUE FOR field-name: 


where DATATRIEVE replaces "field-name" in the message 


Effects 


Examples 
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with the name of the field being sought. DATATRIEVE 
waits for your response, and if accepted, proceeds’ to 
the next seguential field in the record definition, 
until all fields have been filled. 


1. The fields are added to the record in the order in 
which they are provided. If any piece of data is 
inappropriate for its definiton, assumptions are 
made or error messages issued, and the command 
continues on to the next defined field. If a 
numeric field was oversize and contained numeric 
data, the high-order digits were truncated and an 
error message issued. ‘If an alphanumeric field 
contained - excessive string data, truncation 
occurred without an error message. 


2. The collection cursor remains unchanged. The newly 
added record is not in any collection. If you want 
to print this record, you must first establish a 
collection that contains it, and then select it. 


The following example stores a new yacht record in the 
domain YACHTS. Observe that this choice of format 
causes DATATRIEVE to prompt you for the data items. 


DTR>STORE YACHTS; 


PLEASE SUPPLY VALUE FOR MANUFACTURER: DONOVAN 
PLEASE SUPPLY VALUE FOR MODEL: 34LK 

PLEASE SUPPLY VALUE FOR RIG: SLOOP 

PLEASE SUPPLY VALUE FOR LENGTH-OVER-ALL: 34 C#r) 
PLEASE SUPPLY VALUE FOR DISPLACEMENT: 4000 (Cr) 
PLEASE SUPPLY VALUE FOR BEAM: 12 

PLEASE SUPPLY VALUE FOR PRICE: 32000 


If you had merely wanted to open a new record with only 
the manufacturer, model, and type of rig for the data 
items, you could have done the following: 


DTR>STORE YACHTS BEGIN Car) 
DTR>MANUFACTURER="DONOVAN"; MODEL="34LK"; 
DTR>RIG="SLOOP"; END; Cet) 


2 
~~ me so 


@é next example first obtains data for a new yacht 
ecord, and then performs a series of IF statements 
(Section 4.13.5) to test for undesirable data values. 
If any are found, the STORE function does not occur. 
If the record passes these tests, the record is printed 
and the user is given the opportunity to review and 
approve it in its entirety prior to storing it. 


kK 
Li 


HY 


Hints 
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DTR>STORE YACHTS VERIFY USING 
DTR> BEGIN Ce) 


DTR> IF BEAM EQ 0 THEN ABORT "BAD BEAM" 

DTR> IF DISP EQ 0 THEN ABORT "BAD DISPLACEMENT" Cr) 
DTR>”°” “IF NOT LOA BETWEEN’ 20° AND 60 THEN ABORT Cer) 
DTR> "BAD LENGTH" 

DTR> PRINT Ct ) . 

DTR> DISPLAY "CONFIRM WITH Y IF OK" Cer) 

DTR> IF *.CONFIRMATION NE "Y" THEN Caer ) 

DTR> ABORT "STORE ABORTED" 


DTR> END 


In this case, because the PRINT command occurs’ within 
the VERIFY operation, the record of interest (which is 
not the CURRENT one), is the one displayed. 


If you do not use the VERIFY option, make a practice of 
printing out each new record upon completion of a 
successful STORE command. This way, you may detect 
incorrect or omitted data items. Corrections can be 
made by using the MODIFY command (Section 4.9), once 
you have selected (Section 4.6) the new record. 

As in the MODIFY command, explicit checking is not 
performed, but certain violations will be recognized if 
DATATRIEVE uncovers. an incompatibility while moving new 
data into its reserved area. 


When in full prompt mode, you will not be permitted to 
skip over a data item by responding with just a 
carriage return ((Cz#r)). If you do, you will be 
prompted again to supply the same field. However, you 
can leave a data item empty or zero-valued by entering 
a Single space before the carriage return. 


A final hint is to consider the use of the REPEAT 
statement (Section 4.13.3) in conjunction with the 
STORE command whenever you must create a series of 
records in a given session. For example, observe how 
the following combination of the two commands’ saves 
operator input time: 


DTR>REPEAT 3 STORE YACHTS BEGIN (#r ) 
DTR>MANUFACTURER="DONOVAN"; 

DTR>MODEL=* .MODELNAME; 

DTR> RIG="SLOOP"; 

DTR>END; 

PLEASE SUPPLY VALUE FOR MODELNAME: 35LK Cer) 
PLEASE SUPPLY VALUE FOR MODELNAME: 36LK Cr) 
PLEASE SUPPLY VALUE FOR MODELNAME: 37LK (er) 
DTR> 


In the example above, you created three new records, 
having three fields with nonzero or nonblank values. 
Two of the fields were common to all three _ records; 
therefore, with the use of the REPEAT statement and the 
value expression of the form *.prompt-name, you created 
a situation where the only data input was for the field 
that varied from record to record. Had ten or more 
records been involved, the savings would seem even more 
significant. 
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4.12 SOME SPACE CONSIDERATIONS 


Since DATATRIEVE keeps control information and record buffers’ for 
active collections in memory, it is important to keep the memory 
overhead as low as possible. Two commands facilitate this: RELEASE 
and FINISH. Invoke RELEASE whenever you are sure you have finished 


using a named collection. FINISH serves a Similar function for 
domains. 
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RELEASE 


'4.12.1 When You're Done With a Collection -- RELEASE 


Purpose 


Format 


Requirements 


Prompts & 


Responses 


Effects 


Examples 


This command effectively removes a named collection 
from the system to free space for other uses. Note 
that it is the collection kept in temporary storage 
that is lost, but the records and domains from which it 
originated are unaffected. If necessary, the released 
collection can always be reestablished later. 


RELEASE collectn-name-1 [,collectn-name-2...] 


l. You must supply at least one legitimate collection 
name. CURRENT is a legitimate collection name for 
an unnamed collection, if it is the CURRENT one. 


2. You may optionally wish to name additional 
collections for release. The collections need not 
be formed from the same source domain. 


There should be one or more named collections in your 
domains. 


None. 


1. The collections are removed in the order in which 
they are named in the command. 


2. If the command fails while looking for subsequent 
collections, you will find that the collections up 
to the problem collection have been lost. However, 
the problem collection and any following 
collections have not been touched. 


The following example releases the SMALL-BOATS 
collection. 


DTR> RELEASE SMALL-BOATS; ; 


The following example illustrates how to release three 
collections: 


DTR> RELEASE SMALL-BOATS ,MEDIUM-YACHTS , LARGE-YACHTS ; 


Hints 
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Cultivate the habit of releasing collections as soon as 
you know you have finished with them. 


Note that an unnamed CURRENT collection is always 
automatically released by the next successful FIND 
command. 


The FINISH command (Section 4.12.2) RELEASES all 
collections belonging to the domains it operates on. 
Thus, it is redundant to specify a RELEASE command 
followed by a FINISH command involving the same domain. 


Likewise, if you intend to EXIT immediately after this 
RELEASE command, it is unnecessary to use the RELEASE 
command. EXIT performs the RELEASE function for you. 
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FINISH 


4.12.2 When You're Done With a Domain -- FINISH 


Purpose 


Format 


Requirements 


Effects 


Examples 


Hints 


This command deactivates one or more domains to free 
space and/or to permit other users to gain access. You 
do not remove the domain or its records, you merely 
relinquish any previous claims to it made through an 
earlier READY command in this session. 


FINISH [domain-name-1 [,domain-name-2...]] 


1. If you do not specify any domain names, all your 
READY domains are deactivated. 

None. 

None. 

1. The named domains that were READY are deactivated 


so that they are no longer READY and cannot be the 
subject of any FIND commands. 


2. If you name a domain that never was 
receive an error notification. 


READY, you 


3. Any collections that existed for the domain are 


RELEASEd. 


The following example finishes the domain YACHTS. 
DTR>FINISH YACHTS; 


The following example illustrates how to finish all 


ready domains. 


DTR>FINISH; 


If you accidentally FINISH a domain you want READY, you 
can simply READY it again. 


If you intend to EXIT immediately after this FINISH 
command, it is unnecessary to use the FINISH command. 
EXIT performs a FINISH for you. 
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4.13 COMBINING DATATRIEVE-11 COMMANDS 


There are a few additional statements you can learn that will permit 
you to combine DATATRIEVE-11 commands in powerful ways. These 
capabilities may have more significance to the designers of procedures 
(Chapter 6), but are available to all DATATRIEVE-11 users. They are 
therefore brought to your attention. 


These statements employ some elements you have already learned: the 
record selection expression and the simple forms of the FIND, SORT, 
MODIFY and PRINT commands. The statements will be explained first and 
then some examples of how to combine them effectively will be given. 
You have actually already seen three of these, the BEGIN-END Block, 
the assignment statement, and the REPEAT statement, all in 
explanations of the STORE command; but they will be introduced more 
formally now. 
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BEGIN-END Biock 


4.13.1 BEGIN-END Block 


Purpose 


Format 


Requirements 


Prompts & 
Responses 


Effect 


Examples 


This statement groups the enclosed statements into a 
single compound statement. This facility is employed 
in the STORE command (Section 4.11). 


BEGIN statement-1l] [: statement-2...] END 


1. You must supply at least one assignment statement 
(Section 4.13.2). 


Conform to the requirements of the STORE and assignment 
statements. Section 4.11 describes the STORE command. 
Section 4.13.2 describes the assignment statement. 


1. The statements are executed in the sequence 
entered. 


The following example shows the use of a BEGIN-END 
Block with the STORE command. The effect will be to 
store a new record in the domain YACHTS for a 24-foot 
yacht built by Dufour with a model number of 24. 


DTR>STORE YACHTS USING C2: ) 
DTR> BEGIN 

DTR> BUILDER="DUFOUR" C2 ) 
DTR> MODEL="24" 

DTR> LOA=24; 

DTR> END; 
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Assignment Statement 


4.13.2 Assignment Statement 


Purpose 


Formats 


Requirements 


Prompts & 
Responses 


Effects 


The assignment statement provides an alternative method 
of establishing field values in the STORE command. The 
value is supplied by the statement itself, either 
explicitly or by reference to another field name. This 
differs from the technique of the MODIFY command 
(Section 4.9) since in that case you merely identified 
the changing field(s) by name, and then DATATRIEVE 
requested the new data item-by-item. 


field-name-l = value-exp-l 


1. Field-name-l must be defined in the record 
definitions for the source domain. 


2. Value-exp-1 must be a legal value expression. 


field-name-2 = field-name-3 


1. Field-name-2 and field-name-3 must each be group 
data items. 


2. These groups must have at least one identically 
named elementary data item. This name may be the 
defined name or the substitutable QUERY-NAME. 


The record must exist in a source domain that you have 
readied for WRITE or EXTEND access. 


None, unless value-exp-1 assumes the form of 
*.,promptname or **,promptname. 


l. The fields are added to the record in the order in 
which they are provided. If any piece of data is 
inappropriate for its definition, assumptions are 
Made or error messages issued, and the command 
continues on to the next defined field. If a 
numeric field was oversize and contained numeric 
data, the high-order digits were truncated, and an 
error message issued. If an alphanumeric field 
contained excessive String data, truncation 
occurred without an error message. 


2. The collection cursor is left unchanged. 


Example 


Hints 
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The following example uses three assignment statements 
ina BEGIN-END Block within a STORE command to place a 
value of $9000 in the price field in thé new record. 





DTR>STORE YACHTS BEGIN C(t ) 
DTR> BUILDER="SEAWORTHY" 
DTR> MODEL="SW I" 

DTR> PRICE = 9000; END; 


The second format of the assignment statement is used 
primarily to restructure data. This topic is described 
separately for the Data Administrator in Section 7.3. 


Note that you must use the equals sign symbol (=) not 
the Boolean operator EQ. 


No editing is performed on the data you supply. 


The final example in the Hints section for the STORE 
command (Section 4.11) illustrated the use of 
*,prompt-name as the value expression in the assignment 
statement. Consider now, the effect of **,prompt-name 
in a similar situation. The value expression using the 
double asterisks has special meaning in a situation 
where repetition is planned. The value expression 
** ,prompt-name effectively asks for this value just one 
time when inside a REPEAT or FOR loop. Once the value 
is supplied, it is used for its purpose repetitively 
and no further requests are made of the user for this 
item. For example, although the model number is 
requested three times in the example below, the beam is 
only requested once. 


DTR>REPEAT 3 STORE YACHTS BEGIN Cer ) 
DTR>MANUFACTURER= "DONOVAN"; 

DTR>MODEL=* .MODELNAME; 

DTR>RIG="SLOOP"; 

DTR>BEAM=** ,.BEAMSIZE; 

DTR>END; 

PLEASE SUPPLY VALUE FOR MODELNAME: 35LK( et) 
PLEASE SUPPLY VALUE FOR BEAMSIZE: 12 
PLEASE SUPPLY VALUE FOR MODELNAME: 36LK (:t) 
PLEASE SUPPLY VALUE FOR MODELNAME: 37LK C2) 
DTR> 


REPEAT 
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4.13.3 REPEAT Statement 


Purpose 


Format 


Requirements 


Prompts & 


Responses 


Effect 


Example 


Hints 


This statement causes the immediately following 
statement to be executed a given number of times before 
execution progresses on to the next command. This 
clause can save you a great deal of tiresome 
repetition. 


REPEAT value-exp-l statement-1l 
1. You must supply a value expression for the 


number of times to repeat the action (Section 
4.5.1) e 


None. 


None, unless value-exp-1l assumes the form of 
* promptname or **.promptname. 


l. The subsequent statement is executed as many times 
as dictated by the value supplied. 


The following example adds 20 new yacht records to the 
domain. 


DTR> REPEAT 20 STORE YACHTS Cet ) 


Remember that with the combination of REPEAT and STORE 
you can propagate a simple error through a great deal 
of data. 
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THEN 


4.13.4 THEN Statement 


Purpose 


Format 


Requirements 


Restrictions 


Prompts & 


Responses 


Effects 


Example 


This connecting word joins commands or statements’ so 
that execution of the second statement immediately 
follows the first. 


statement-l THEN statement-2 


1. You must supply two statements. You may choose any 
of the commands, used singly or in combinations for 
these statements, with two exceptions. Do not use 
the FIND command with SELECT, and do not use ABORT 
(Section 4.13.6) for statement-l. 


Conform to the requirements of the statements. 


Do not use the combination FIND 
specify an ABORT statement for s 


ct &} 


As provided by the statements being executed. 


1. The first statement executes, followed by the 
second one. 


2. Other effects depend on the choice of statements. 


The following example directs DATATRIEVE-1l to print 
the type and price of the CURRENT yacht and then modify 
the price. 

DTR>PRINT TYPE, PRICE THEN MODIFY PRICE; 
MANUFACTURER MODEL PRICE 


AMERICAN 26 $9,898 
PLEASE SUPPLY VALUE FOR PRICE: 10,898 Cx) 


Hint 
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You may issue a number of successive THEN statements if 
meaningful. For example, you could enter the following 
commands: 


DTR>READY YACHTS EXTEND 
DTR>STORE YACHTS USING Ce) 


DTR> BUILDER = "DONOVAN" THEN (a) 
DTR> MODEL = "DV24"; 
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IF-THEN-ELSE 


4.13.5 IF-THEN-ELSE Statement 


Purpose 


Format 


Requirements 


Prompts & 


Responses 


Effects 


Example 


This statement provides a limited choice of actions 
that may be followed based on existing conditions. 


IF condition THEN statement-1 [ELSE statement-2] 


1. You must supply a condition in the form of a 
Boolean expression (Section 4.5.2). 


2. You must supply an action to be taken, in the form 
of statement-l. Statement-l may be a simple or 
compound command. 


3. You may optionally want to specify a second 
possible action in the form of statement-2. 
Statement-2 may be a simple or compound command. 


Conform to the requirements of the statement (s) 
specified. 


As dictated by the statement(s) specified. 


1. The condition is tested and if and only if it is 
true, sStatement-l is executed. If the condition 
proves false, any optional statements following the 
word THEN will be executed. 


2. The execution proceeds to the next DATATRIEVE-11 
command. 


The following example tests if LOA is greater than 99. 
If it is, the user wishes to MODIFY the field. 
Otherwise, the execution can proceed to the next 
command. 


DTR>IF LOA>99 THEN MODIFY LOA; 
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Hint 


You may nest your IF statements. For example, the 
following sequence would classify a yacht by size and 
recognize any yacht that was oversize. It employs’ the 
DISPLAY statement described in Section 4.13.7. 


DTR>IF LOA BETWEEN 0 AND 26 THEN DISPLAY "SMALL-YACHT" ELSE Cet) 
DTR>IF LOA BETWEEN 27 AND 32 THEN DISPLAY "MEDIUM-YACHT" ELSE Cer) 
DTR>IF LOA BETWEEN 33 AND 99 THEN DISPLAY “LARGE-YACHT" ELSE Cr) 
DTR>DISPLAY "THIS YACHT IS WRONG LENGTH" Ct) 
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ABORT 


4.13.6 ABORT Statement 


Purpose 


Format 


Requirements 


Prompts & 
Responses. 


Effects 


Example 


Hint 


The ABORT statement provides a means of terminating 
command execution in a compound statement. Note that 
it only affects the one command or statement under 
consideration; it does not affect the DATATRIEVE-11 
session as a whole. . 


ABORT value-exp-1l 


1. Value-exp-l must be a value expression. (See 
Section 4.5.1.) 


None. 


1. If the ABORT action takes place, whatever value you 
specified for value-exp-1 will be displayed on your 
terminal device, followed by the notification 


eve fremr As monyrwaAmon oy mu 


EXECUTION TERMINATED BY "ABORT" CO 
2. The collection cursor is left unchanged. 


3. You are prompted to enter the next DATATRIEVE 
command. 


The following example shows the use of the ABORT 
statement in combination with an IF-THEN-ELSE 
statement, for a record whose model number is not 345T. 


DTR>IF MODEL EQ "345T" THEN MODIFY PRICE ELSE () 
DTR>ABORT "NOT MODEL 345T"; 

ABORT: NOT MODEL 345T 

EXECUTION TERMINATED BY "ABORT" COMMAND 

DTR> 


In the example below the concatenation character (;) is 
used to construct a value-expression that provides a 
more informative message. 


DTR>IF MODEL EQ "345T" THEN MODIFY PRICE ELSE Ct) 
DTR>ABORT "MODEL NO. IS: "|MODEL C=) 


DISPLAY 
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4.13.7 DISPLAY Statement 


Purpose 


Format 


Requirements 


Prompts & 


Responses 


Effect 


Example 


Hints 


This statement causes DATATRIEVE to immediately print 
the value specified. This facility lets you conduct 
brief checks on certain results while some operation is 
in progress. It is clearly not intended for writing 
large amounts of data; the PRINT command or Report 
Writer facilities are better choices for that. 
However, the DISPLAY statement can be a handy tool for 
displaying limited quantities of data, especially when 
you recall the range of items qualifying as value 
expressions (Table 4-2). 


DISPLAY value-exp-1l 


1. You must supply a value expression. Refer to 
Section 4.5.1. 


None. 


None, unless value-exp-l assumes the form of 
*,promptname or **,promptname. 


1. The value of the value expression is displayed on 
your terminal. 


The following example shows the DISPLAY statement used 
with an IF-THEN-ELSE statement. 


DTR>IF PRICE>35000 THEN DISPLAY C2) 
DTR>"OVER-BUDGET" ELSE PRINT BUILDER; 


MANUFACTURER 


AMERICAN 


You could use the DISPLAY statement in a REPEAT-STORE 
compound statement to send an intermediate message to 
the user. For example, in the illustrated sequence 
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below, the reminder to ENTER NEXT RECORD precedes’ each 
request for data and sort of documents the beginning of 
each new record. 


DTR> REPEAT 3 DISPLAY “ENTER NEXT RECORD” THEN Ger) 
DTR>STORE YACHTS USING 
DTR>BUILDER = "DUFOUR" C=) 


You may want to consider the use of the concatenation 
character (;) to create a more informative message. 
See the Hint section of the ABORT command (Section 
4.13.6). 


FOR 
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4.13.8 FOR Statement 


Purpose 


Format 


Requirements 


Prompts & 
Responses 


Effects 


Example 


This statement specifies that the substatement that 
follows must be performed on the group of records 
identified by the record selection expression. 


FOR rse-l statement-l 


1. You must supply a record selection expression. See 
Section 4.5. 


2. The substatement statement-l may be a command or 
two or more commands linked by the word THEN 
(Section 4.13.4). 


The domain identified by the rse must be READY. 


You must obey the requirements of any command you 
invoke as statement-l. 


The prompts and responses will be dictated by your 
choice of command(s) for statement-l. 


1. On READY domains, there is no prerequisite that 
FIND (unless CURRENT is specified in the rse) 
and/or SELECT be executed. The collection will be 
temporarily "found" (but not established) for you 
and processed. This part of the processing will 
not affect the cursor either. 


2. The final effects will depend on your choice of 
command(s) for statement-l. 


The following example identifies the records of yachts 
Manufactured by Pearson for modification of the price. 


COMMANDS FOR INQUIRY & UPDATE 


DTR>FOR YACHTS WITH Cer) 
DTR>BUILDER EQ "PEARSON" PRINT MODEL, PRICE THEN Cet) 
DTR>MODIFY PRICE; 


MODEL PRICE 
26 $11,000 

PLEASE SUPPLY VALUE FOR PRICE: 11500 C#~) 
26W $10,000 


PLEASE SUPPLY VALUE FOR PRICE: 10500 
DTR> 


HELP 


4.14 


Purpose 


Format 


Requirements 


Prompts & 
Responses 


Effects 


Examples 
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GETTING ASSISTANCE WITH THE HELP COMMAND 


This command requests assistance with one or more 
commands. Two forms of help are available, since the 
commands can be thought of in two categories: simple 
and advanced. You only enter the realm of the advanced 
form Of any command when you employ the optional 
elements such as the record selection expression. 


HELP [ADVANCED] [commnd-name-1[,commnd-name-2...]] 


1. If you specify one or more command-names, they must 
each be legitimate DATATRIEVE commands. 


2. You may optionally specify that you wish the more 
advanced type of assistance by specifying the word 
ADVANCED. 


None. 


No prompting messages appear, but you will be informed 
how to use the command or commands you specified. 


None. 


The following example requests help with the simple 
forms of the FIND and SELECT commands. 

DTR>HELP FIND, SELECT; 

The following example illustrates how to obtain 
assistance with the more complex forms of the FIND and 


MODIFY commands. 


DTR>HELP ADVANCED FIND, MODIFY; (#1) 


CHAPTER 5 


COMMANDS FOR REPORT WRITING 


This chapter presents the commands that are part of the DATATRIEVE-11 
facility for report writing. These commands are entered in a group or 
block, that we will call the RW sequence. Before learning how to 
construct an RW sequence, you should review the parts of a report. 


5.1 PARTS OF A REPORT 


The Report Writer allows you extensive flexibility in designing a 
report. The flexibility, however, means that a generalized report may 


harwa a laraa nimhar af annmnnnanta Dar example KAA liek At manaathia 
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components includes report headers, column headers, report sections, 
detail lines, summary lines, report groups, and report events. 
Because we will refer to each of these parts by name, it is important 
for you to understand what they are. Figure 5-1 illustrates a typical 
report and its parts. 


The REPORT HEADER is the line or lines that may be printed at the top 
of your report, usualiy as a titie. The report header may inciude the 
report name, date, and page number or any combination of these three 
items. Nearly all reports will contain a report header on the first 
page; at your option, you may request that the header be printed on 
subsequent pages or subsequent sections. 


The COLUMN HEADER consists of one or more lines printed as the headers 
for the columns in the report. The column header may include field 
names, DATATRIEVE keywords, or other headers that you have specified. 


A REPORT SECTION is just what it sounds like: a section of a report. 
A report section begins on a new page, numbered one. You might want 
to divide the report into sections when you plan to separate it and 
send the various sections to different people. 


One or more lines in the report that are produced from a data _ record 
in the file are collectively called the DETAIL LINE. The detail line 
need not be straight from the file; the RW allows you to add literal 
strings and arithmetic expressions. For example, you could add an 
arithmetic expression such as PRICE/DISP to calculate the cost per 
pound for each yacht. The resulting value would become part of the 
detail line in the generated report but not part of the data record. 


A number of successive input records with a single value for a 
particular field constitutes a REPORT GROUP (sometimes just called a 
group). The end of a report group is reached when the next record has 
a different value for the field in question. Report groups are often 
a useful key for formatting indentation and spacing. You can create 
subgroups by specifying more than one sort-key. 


COMMANDS FOR REPORT WRITING 


The beginning or end of a report group or the top or bottom of a page 
or report is called a REPORT EVENT. You can request that various 
procedures take place when a report event occurs. For example, at the 
bottom of a report group, you might want to print totals or subtotals 
for one or more fields. 


In addition to invoking special procedures, a report event can trigger 
a SUMMARY LINE. Summary lines can include summary information (for 
example, any of the statistical functions TOTAL, COUNT, AVERAGE, MAX, 
or MIN) for a report, page, or report group, but they are not limited 
to such information. A summary line can also contain header 


information for groups, pages, or reports, or perhaps start a new page 
or section. 


In the sections that follow you will learn Report Writer statements 
that specify these parts of a report. After all the statements have 
been discussed individually, Figure 5-2 illustrates some RW sequences 
that combine the statements. 
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LISTING OF SAILBOATS BY LENGTH AND TYPE<«——— 


LENGTH RIG MANUFACTURER MODEL WEIGHT BEAM PRICE 


CHALLENGER 41] 26,700 13 
GULFSTAR 41 22,000 12 
ISLANDER FREEPORT 22,000 13 


COLUMBIA 20,700 1l 





OLYMPIC ADVENTURE 24,250 13 


AVERAGE PRICE: $55,308 





REPORT GROUP A consists of four records all having a length of 41 feet. 

REPORT GROUP B consists of one record having a length of 42 feet. 

* EVENTS occur here when the rig type changes from KETCH to SLOOP | 
n the sailboat length changes from 41 to 42 feet. 


Figure 5-1 Parts of a Report 
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REPORT 


5.2 INVOKING RW -- REPORT 


Purpose 

This statement invokes the Report Writer facility of 

DATATRIEVE-11. You may obtain a report on any collection 

or domain that is already established. 

Format 

REPORT [rse] [ON file-spec-1] 

where the record selection expression (rse) assumes’ the 

form: 

ALL CURRENT 
FIRST n| [collectn-name-2 IN collectn-name-3} [WITH conditn] 
domain-name-1 

[SORTED BY key-l[,key-2...]] 

Note that n represents any decimal integer. 

If necessary, review the descriptions of record 

selection expressions in Section 4.5.3. 

1. If you specify a record selection expression, you 
will obtain a report on the records in the 
collection or domain you designate. 

2. If you omit the record selection expression, the 
report witi include the CURRENT collection data 
only. 

3. If you specify the optional [ON file-spec-1] 
clause, file-spec-l must be the name of a file or 
device specification. If you do not designate a 
special file specification, the report appears on 
your terminal. Note that you can use the 
value expression * ,prompt-name (described in 
Section 4.5.1) to obtain a file or device 
specification. 

Requirements 
You must have already established a collection if you 
specify CURRENT or a collection name. 

Prompts & 

Responses 
None. 

Effects 


1. The report reflects only the CURRENT collection 
data unless you supply a collection name in the 
record selection expression. 


Examples 


Hints 
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2. The output of the report is directed to _ the 
terminal unless you provide an alternate file 
specification in the ON file-spec-1l clause. 

3. The Report Writer treats all the subsequent input 
as RW statements until you issue the REPORT END 
statement. 


4. The collection cursor is left unchanged. 


The following example initiates a report for the 
CURRENT collection to be printed on the terminal. 


DTR> REPORT; 


The following example initiates a report for the 
MEDIUM-YACHTS collection with the specified 
characteristics to be printed on line printer unit 2. 


DTR>REPORT FIRST 7 MEDIUM-YACHTS WITH PRICE< (er) 
DTR>40000 SORTED BY LOA ON LP2:; 


The ability to print the report on your terminal may be 
especially useful for preparing a "trial run" of a 
report. This way you can check the spacing and format 
before you print the report on the line printer or 


other device, 


While there is no provision in the REPORT command 
syntax for specifying that you wish multiple copies of 
your report, you could always use _ the following 
technique to obtain them. First generate a copy of the 
report into a named area (for example, REPORT ON 
REP1.SAV), and then use an operating system command to 
queue multiple listings of that file from the area. 
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REPORT END 


5.3 TERMINATING THE REPORT -- REPORT END 


Purpose 


Format 


Requirements 


Prompts & 
Responses 


Effects 


Example 


The REPORT END statement is the last statement in an RW 
sequence. It Signals DATATRIEVE that subsequent 
commands are not to be treated as part of the RW 
sequence. Upon recognition of the REPORT END 
statement, DATATRIEVE begins to check the complete RW 
sequence for syntax errors. If none is’ found, 
execution of the report request begins. Otherwise, 
error messages appear on your terminal and you must 
correct the errors before your request can be 
processed. 


REPORT END 


You must have previously issued a REPORT statement, a 
SET REPORT-NAME statement, and at least one PRINT or AT 
statement. 


None. 


1. DATATRIEVE scans all the RW statements for syntax 
errors. If none is found, the report you requested 
will be printed on the specified device. If any 
errors are present, you must correct them before a 
report can be printed. 


The following example ends a sequence of RW commands. 


DTR>REPORT END; 


5=6 
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SET 


5.4 SPECIFYING REPORT PARAMETERS -- SET 


Purpose 
This statement defines values for one or more 
parameters throughout the report. You can set the 
following items: 
e Report name 
e Maximum number of lines per report 
@e Maximum number of pages per report 
e Page numbering or no page numbering 
e Date or no date 
e@e Number of lines per output page 
e Number of columns per output page 
Format 
SET parameter-1 [,parameter-2...] 





where the parameters are chosen from the following 
list: 


REPORT-NAME = report-name 
MAX~LINES = integer-l 
MAX-PAGES = integer-2 
NUMBER 

NO-NUMBER 

DATE = ["string-1"] 
NO-DATE 

LINES-PAGE = integer-3 
COLUMNS-PAGE = integer-4 


1. REPORT-NAME must consist of one or more name 
segments, separated by slashes. The name segments 
must be literals (see Section 3.8). DATATRIEVE-11 
centers the segments on successive lines. 
REPORT-NAME must be set once in every RW sequence. 


2. Integer-1 denotes the maximum number of lines’ that 
the report may include. If the number of lines 
(including blank lines and lines automatically 
skipped) exceeds this number, DATATRIEVE-11 
automatically terminates the report. If you omit 
this parameter, no checking is done, and the report 
may run until terminated by outside intervention. 


3. Integer-2 indicates the maximum number of output 
pages that the report may span. DATATRIEVE-11 
automatically ends the report after printing this 
number of pages. If you omit this parameter, no 
checking is done and the report may run_ until 
terminated by outside intervention. 


Requirements 


Prompts & 
Responses 


Effects 


Examples 


Hint 
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4. NUMBER and NO-NUMBER, respectively, allow you _ to 
include or exclude page numbers in the report. 


5. DATE and NO-DATE, respectively, allow you to 
include or exclude the date of your report. The 
DATE parameter has an optional string-1l clause. 
If you omit this clause, DATATRIEVE-11 uses the 
current system date in the format dd-mmm-yy, as in 
18-AUG-77. By including the string-l clause, you 
can specify a particular date in any format you 
want. For example, DATE="OCTOBER 31, 1977" or 
DATE="HALLOWEEN" are two acceptable forms. 


6. Integer-3 represents the number of lines to be 
printed on each output page. If you omit this 
specification, DATATRIEVE-1l automatically uses a 
value of 60. 


7. Integer-4 denotes the number of columns to _ be 
printed across’ the output page. If you omit this 
value, DATATRIEVE-11 automatically uses a value of 
132. The maximum value of integer-4 is 132. 


None. 


None. 


1. DATATRIEVE-11 sets values for all the parameters 
included in the SET statement. These values 
pertain to the entire report. 


2. If certain parameters are not set, DATATRIEVE-11 
adopts the default values shown in Table 5-1. 


The following example sets a report name. 


DTR>SET REPORT-NAME = "YACHT SALES"/ Ct) 
DTR>"IN CALENDAR YEAR 1977"/ Ce) 


| ey somerecereai. 


DTR>"“STAR-KEY MARINA, INC.” Carer 


The second example sets a value of 58 lines per page 
and 72 columns per page. 


TR>SET LINES-PAGE = 58, COLUMNS-PAGE = 72; Cr ) 


If you need to set several parameters in the same 
report, you can use more than one SET statement. The 
additional SET statements may not, however, be used to 
change parameters that have already been set. 
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Table 5-1 
Default Report Parameters 


Parameter | Default Value 


REPORT-NAME None. Required 
MAX-LINES None. Not required, 
MAX-PAGES None. Not required 


NUMBER Pages will be numbered. 


DATE Current date in computer is used. 


LINES-PAGE 60 


COLUMNS~PAGE 





PRINT 
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5.5 FORMATTING DETAIL LINES -- PRINT 


Purpose 


Format 


Requirements 


Prompts & 
Responses 


Effect 


Example 


This statement specifies the content and format of a 
detail line in the report. 


PRINT detail-item-1 [,detail-item-1...] 


1. Detail-item-l and detail-item-2 are the same print 
list elements that were defined in Table 4-5. See 
Section 4.8 for a complete description of the PRINT 
command, 


2. You may specify only one PRINT statement to specify 


the detail line format in each report 
specification. 

None. 

None. 


1. The RW produces a detail line for each record in 
the collection or domain on which the report is 
based. 


The following example produces a detail line that 
Starts with nine spaces, and then lists the yacht 
displacement and price as recorded in the data record. 
Finally, the price of the boat is divided by its 
weight, and the result is printed in the last column 
under the heading "PRICE PER POUND." 


wRmrraArm 


DTR>PRICE/DISP ("PRICE"/"PER"/"POUND") USING 
DTR>$2Z,222.99; 
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AT 


5.6 FORMATTING SUMMARY LINES -- AT 


Purpos 


Format 


AT 
B 


e 


TOP 
OTTO 


This statement specifies the content and format of a 
summary line in the report. A summary line may appear 
at the top or bottom of a page, report, or field. It 
May include a value, the result of an arithmetic 
calculation, or a report header. The summary line may 
also specify special spacing instructions, a new page, 
or a new section of the report. 


REPORT 


field-name-1 
} OF PAGE PRINT summry-item-1 [,summry-item-2.. 
M 
Ps 


Field-name-1l must name a field that belongs to the 
record type associated with the collection on which 
you are reporting. 


2. Table 5-2 lists all the legal values for summary 
items. Note that since a modified PRINT statement 
is part of the AT statement, many of the iegai 
options of the PRINT statement may be used in the 
summary items as well. 


3. The value expression is evaluated using the first 
or last record of the group, the page, or the 
collection, depending on the summary line 
specification. 


4. If you specify TOTAL, COUNT, AVERAGE, MAX, or MIN, 


RW computes the quantity for the field, page, or 
report. These specifications may only be part of 
an AT BOTTOM statement; you cannot summarize a 
column, page, or report in this manner at the top. 


5. NEW-PAGE signals two report events: 


BOTTOM OF PAGE 
TOP OF PAGE 


Any procedures specified for the top or bottom of 


the page will be executed whenever a NEW-PAGE is 
specified. 


6. NEW-SECTION signals three report events: 
BOTTOM OF PAGE 
TOP OF REPORT 
TOP OF PAGE 


After each new section is started, RW resets’ the 
page numbers to l. 
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Unless you explicitly specify otherwise, RW 
automatically performs the following statement each 
time it starts a new page: 


AT TOP OF PAGE PRINT REPORT-HEADER, COLUMN-HEADER; 


If you sorted the collection before invoking RW, RW 
Maintains the order imposed by the sort. 


If you specify more than one AT TOP or AT BOTTOM 
statement, and the values of one or more fields 
change between successive input records, RW does 
not execute the AT TOP and AT BOTTOM statements in 
the order in which you typed them. Instead, it 
executes them in the order in which you specified 
the sort-keys before invoking the Report Writer. 


Requirements 
None. 
Prompts & 
Responses 
None. 
Effect 
1. If you specify more than one summary item, the 
procedures the summary items imply are executed in 
the order in which they are implied. For example, 
items specifying AT TOP result in printing at the 
top of the named item, while those carrying AT 
BOTTOM notations are saved and printed at the end 
of the report group. 
Examples 


The following example identifies the report event of a 
change in the length-over-all field, and causes the new 
LOA value to be printed under the column header LENGTH 
at the beginning of each report event. 


DTR>AT TOP OF LOA PRINT LOA("LENGTH") ; Ce) 


The next example prints both the report name and column 
headers at the beginning of each new page. 


DTR>AT TOP OF PAGE PRINT REPORT-HEADER, COLUMN-HEADER (®t) 
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Table 5-2 
Summary Items 


Advances across the horizontal line to column 
n. Note: n must not be less than one or more 
th idth. If n less than the 








TATTA 


th Ke 1 
tnan tne page Ww ainii 


present column, a line is skipped. 
SKIP [n] Moves n blank lines ahead to start a new line. 
Printing starts in column one, unless another 
element modifies the position further. 
TOTAL field-1l Causes a total to be printed for the field at 
the bottom of the page or report. 


COUNT Causes the number of items in the page, field, 
or report to be printed. 


field-1 to be printed. 


MAX field-1l Causes the maximum value in the field to be 


printed. 


MIN’ field-l Causes the minimum value in the field to be 


printed. 


NEW-PAGE Forces a new page at this point in the report. 


Note that this phrase activates any TOP OF 
PAGE statements that you have specified. 


printed 
NEW-SECTION £f a new section of the 
a 


auses the beginni 
eport. Page numbers 


nryn 
1iy Vw 


aa 










repo 
| AVERAGE field-1l | Causes the average of all the values’ for 
| r re restarted at one. 
| REPORT-HEADER Causes the printing of the report header, as 
specified via the SET REPORT-NAME command. 


COLUMN-HEADER Causes the printing of the column headers. 
value-expression 


Causes a value to be inserted in the report. 
[modifiers] 


See Table 4-5, 









NOTE 


The TAB specification, although 
permitted in the PRINT command, is not 
permitted here. 
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DNTROREALY YACHTS WRITE 
DTRAFIND YACHTS WITH LOA => 33 
C7 RECORDS FOUND) 

DTROREPORT 5 

DTRSSET REPORT-NAME="TESTING"? 


DTRSSET COLUMNS-PAGE = 50 
DTROF RINT FRICE»BUILDERsRIGs 
DTRoKEFORT ENT 





TESTING 28-OCT-77 

PAGE 1 
PRICE MANUFACTURER RIG 
$347951 ALBERG KETCH 
$37%850 CARIBREEAN SLOOF 
$39 2215 CHALLENGER SLOOF 
$37%850 CHRIS-CRAF SLOOP 
$39 500 I. TRADER KETCH 
$34%950 IRWIN KETCH 
$35%900 LINDSEY M/S 


ITRSREADY YACHTS 

DTRSREPORT YACHTS WITH LOA +36 SORTED BY BUILDERs LOA 
DTR2SET REPORT-NAME = *YACHT SALES*/ 

DTR>"IN CALENDAR YEAR 1977°/ 

DTR>"STAR-KEY MARINA? INC." 

DTROSET LINES-PAGE = 38, COLUMNS-FAGE = 723 
DTROFRINT SPACE 9» DISFs FRICEs 
DTROFRICE/DISF C"FRICE*/*PERS/*POUND") USING 
DTR>$ZZ9ZZZ.993 

DTR>AT TOF OF LOA PRINT LOA ("LENGTH") 
DTROAT TOF OF PAGE PRINT REPORT-HEADER:s — 
DTR>COLUMN-HEATIER + 

DTRSREPORT END 


YACHT SALES 


IN CALENDAR YEAR 1977 28-0CT-77 
STAR-KEY MARINA» INC. FAGE 1 
PRICE 
FER 
LENGTH WEIGHT PRICE FOUND 
37 
2027000 $369951 $ 1.00 
202000 $347950 $ 1.00 
39 
142500 - $359900 $ 200 





Figure 5-2 Sample Report Writer Sequences 
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DTR> READY YACHTS 
DTR> FIND YACHT-TYPES IN YACHTS SORTED BY ASC RIG» 
UTR> BUILDER» LOAs 
_£35 RECORDS FOUND 
DTR» SELECT FIRSTs 
DTR>REFORT YACHT-TYFES: 
DTR> SET REFORT-NAME="YACHTS GROUFED BY TYPE"s 
DUTR> SET COLUMNS-FAGE = 72 
DUTR> AT TOF OF RIG FRINT RIG 


DTR> PRINT BUILDER, LOAs DISFs BEAMy PRICES 
DTR: AT BOTTOM OF RIG PRINT COUNT 
DTR> REPORT END» 


YACHTS GROUFED BY TYFE 28-0CT-77 





LENGTH 
OVER 
RIG MANUFACTURER ALL WEIGHT REAM PRICE | 
KETCH 
| ALBERG 37 20000 12 $36,951 | 
GRAMPIAN 33 12%000 10 $29+475 
| I. TRADER 36 187600 12 $39 7500 | 
| IRWIN 37 207000 11 $361950 | 
4 
M/S 
AMERICAN 26 57500 08 $187895 
EASTWARD 24 77000 09 $157900 
LINDSEY 39 147500 12 $35 7900 
3 
| sLoor 
ALBIN 26 41200 10 $1717900 
ALBIN 27 51070 08 $187600 
AMERICAN 26 41000 08 $9895 
BAYFIELD 32 91500 10 $321875 
CAPE DORY 19 17900 06 $4 7295 
CAPE DORY 25 42000 07 $87995 
CAPE DORY 28 91000 09 $211990 
CARIBBEAN 35 187000 11 $37 1850 
CHALLENGER 32 127800 11 $317835 
CHALLENGER 35 147800 12 $397215 
CHRIS-CRAF 35 187000 11 $377850 
CLIPPER 30 37800 08 $9 9500 
CLIPPER 32 41500 O8 $12+950 
GRAMPIAN 26 57600 08 $117495 
GRAMPIAN 28 67900 10 $14,475 
HUNTER 27 67500 09 $14999 
IRWIN 25 57400 12 $107950 
ISLANDER 24 41200 08 $6 7500 
ISLANDER 28 51994 10 $157908 
RYDER 31 137600 00 $321500 
SABRE 28 77400 09 $22 +000 
SALT 25 21600 07 $67590 
TANZER 26 41350 09 $117750 
TANZER 28 61800 10 $17 +500 
VENTURE 21 17500 07 $2823 
VENTURE 22 21000 07 $39564 
WESTERLY 26 67700 08 $157245 
WINDPOWER 16 650 07 $37500 





Figure 5-2 (Cont.) Sample Report Writer Sequences 
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DTR>!THE RW SEQUENCE THAT CREATED FIGURE 5-1. 

UTR?! 

DTRSREADY YACHTS 

DTR>REFORT YACHTS SORTED BY ASC LOAy RIG 

DTRSSET REF ORT-NAME="LISTING OF SAILBOATS BY LENGTH AND TYPE" 
DTRSSET LINES-FAGE=15 

DTR>SET COLUMNS-FAGE=70 

DTRSAT TOF OF LOA PRINT LOAC*LENGTH")s 

DTRSAT, TOF OF RIG FRINT RIGC("RIG")3 

DUTR>AT BOTTOM OF REFORT FRINT COL 30»- 

DTR>"AVERAGE PRICE: “*»sAVERAGE FRICE USING $2ZZ2Z99 3 
DTR>FRINT TYPE: DISF» BEAM USING Z9» PRICES 
DTR>REPORT END s 


Figure 5-2 (Cont.) Sample Report Writer Sequences 
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CHAPTER 6 


PROCEDURES 


6.1 INTRODUCTION TO PROCEDURES 


Procedures are groups Of DATATRIEVE statements and commands that you 
want to name so that you can cause them to execute without having to 
reenter them each time they are needed. Whether or not you become 
involved in defining procedures, you will probably want to invoke some 
of them as your use of DATATRIEVE expands. The use of procedures can 
save you a great deal of time at the keyboard. Since the sequence of 
commands has been “debugged" prior to its entry in the Data 
Dictionary you can avoid some of the common errors of writing 
mma a ta vt r 


r 
NAMAMDITYPVWVLY an 
MALLEALINA Vi VV 


na 
11uU 


6.2 INVOKING A PROCEDURE 


Once a procedure has been defined and placed in the Data Dictionary, 
you may invoke it by name any time you need it. The technique is to 
issue a colon (:) immediately prior to the procedure name. If you are 
not sure of the procedure name, you can issue a SHOW PROCEDURES 
command (Section 4.3). 


To illustrate this technique, suppose you know there iS a _ procedure 
called PRICE-INCR in your Data Dictionary. Once you ready the domain 
YACHTS for writing, you can invoke PRICE-INCR to display both the 
current value of the price field and the value of the price if 
increased by 10 percent. The procedure asks you to supply the value 
of the price, so that you can modify the old value to the newly 
calculated figure. It repeats this process for every yacht with a 
price greater than zero. This procedure will produce the same results 
that you would have achieved by issuing the following seguence of 
DATATRIEVE commands. (As you would suspect, these commands comprise 
the procedure definition.) 


DTR>FOR YACHTS WITH PRICE > O (C2) 

DTR>PRINT "PRICE: ",PRICE," 10% INCREASE: ",PRICE*1.1 USING C#) 
DTR>SSS$,$$SS THEN MODIFY PRICE; 

DTR>FINISH; 


Invoking this sequence of DATATRIEVE-11 commands is as simple as 
calling its name. You simply precede the name by a colon. You may. 
follow it with an optional semicolon if you wish. 


For example, using the defined procedure PRICE-INCR we could cause a 
10 percent price increase in all the yacht records as follows: 


PROCEDURES 


DTR>READY YACHTS WRITE; 
DTR> : PRICE-INCR Cer) 
PRICE 
PRICE: $36,951 10% INCREASE: $40646.10 


PLEASE SUPPLY VALUE FOR PRICE: 40646 


and so forth. 


You would be informed of the current and calculated price and 


requested to supply a value for PRICE for each of the records in the 
domain. 


CHAPTER 7 


FOR THE DATA ADMINISTRATOR 


This chapter covers some topics of special interest to the Data 
Administrator. The average user will not need to study this 
information. From this chapter the Data Administrator can learn how 
to define records, domains, and procedures, how to maintain-these 
definitions, how to use the data protection features for greater 


installation security, and finally, how to restructure data in 
existing files into other formats. 


7.1 DATA DICTIONARY T 


Before any user can usé DATATRIEVE-1l1 on the records and domains, an 
individual at the installation must first define the records and 
domains. These definitions are retained in the Data Dictionary along 
with the procedure definitions. 


In the following sections you will learn how to use the DEFINE command 
to create the record, domain, and procedure definitions. You will 
also learn how to remove the definitions from the Data Dictionary 


ae ee ase —_s wash —_ve Vee «He 7e 





A general suggestion is offered here since you may find yourself 
wanting to edit your definitions and there is no editing facility that 
operates on the Data Dictionary; (DATATRIEVE-1ll requires that you 
delete a definition and then redefine it). You might consider instead 
setting all your definitions up in indirect command files. These 
files may be edited at will with your operating system's editor. When 
you are satisfied with the definition, you enter DATATRIEVE-11 and 
simply respond to the DTR> prompt with 


@file-name-1 


This technique was employed during DATATRIEVE-11 installation. 
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7.1.1 Defining the Records--DEFINE RECORD 


You must define each field in each record, its size and general 
characteristics. While COBOL programmers will find the format of the 
definitions to be familiar, you should not assume that the RMS-11 
files need to be generated by COBOL programs or that any other 
knowledge of the COBOL language is required. This is simply a 
convenient format for describing the data items and their 
relationships to one another in each record. Even if you have never 
studied COBOL, you should be able to use the elements comfortably once 
you see a few examples. The pertinent COBOL rules have been extracted 
and summarized. They are presented in Appendix E. 


Purpose 


Format 
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DEFINE RECORD 


This command creates a complete record definition in 


the Data Dictionary. This definition will permit 
references to the record and its fields. It is 
necessary, however, that the record also be defined as 
part of a defined domain. This action can take place 
either before or after the record definition, provided 
it occurs before a user attempts the first reference to 
the record. Section 7.1.2 describes how to define a 
domain. 


DEFINE RECORD record-name-l USING data-def-1 [data-def-2...] ; 


1.. You must specify a record name. (See Section 3.7.) 


2. Each record must consist of at least one data item 
(field) requiring a data definition. Additional 
fields will require additional data definitions. 
The definitions must be given in the same 
sequential order as the fields exist in the record. 


3. Data definitions will assume the format of COBOL 
data definitions, employing the technique of a 
PICTURE clause to describe the type of data (for 
example, numeric and alphanumeric) its length, and 
permitted contents. This approach also _ supports 
the use of level-numbers to describe subfields 
within major fields. Each data definition assumes 
the following format: 


level-no fld-nme-1 [PIC IS char-string 


(USAGE IS usage] [SIGN IS qualifiers]] 


You will find descriptions of the optional PIC, 
USAGE, and SIGN clauses in Appendix E. 


You may also intersperse optional clauses such as 


[QUERY-NAME IS name]. 
or 

(QUERY-HEADER IS "header-1"[/"header-2"...]]. 
or 

[EDIT-STRING IS edit-string]. 


These clauses designate abbreviations for the 
field name or abbreviations for the header to be 
used when printing the field on reports, or they 
specify an editing pattern to control the format of 
the data when it is output. The EDIT-STRING clause 
is described in Appendix E. 


4. Observe that each data definition elementary data 
item terminates with a mandatory period. 


5. The semicolon is required for command termination. 
You may also separate the optional clauses by 
semicolons, if you wish. To avoid any possible 
misinterpretation about the period that ends a data 


Requirements 


Restriction 


Prompts & 


Responses 


Effects 


Example 
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definition line and the period that represents a 
decimal point in a character string, particularly 
when followed by a semicolon, you should adopt the 
following practice: 


Place the final semicolon that terminates’ the 
record definition on a line by itself. 


You must not use any of the keywords in your 
definitions as either field names or record names. 
These keywords are described in Section 3.11. You also 
must not duplicate previously defined record, domain, 
or procedure names. 


The DEFINE RECORD command is not permitted in a 
procedure definition. 


None. 


l. Provided you have chosen a unique name for the 
record, your new definition will be placed in the 
Data Dictionary. 


2. A password table (Section 7.2) will be created for 
this resource and your UIC will be entered with 
full access privileges (RWEMC). 


3. If the record name you choose is not unique, your 
command will be rejected. (To modify an existing 
record definition, you must first delete the old 
version with the DELETE command (Section 7.1.4), 
then issue a new DEFINE RECORD command--unless you 
have followed the suggested editing technique of 
Section 7.1 and used indirect command files.) 


The following example defines the yacht record as’ used 
in a number of examples throughout this manual. 


Hints 


FOR THE DATA ADMINISTRATOR 


DTR>DEFINE RECORD YACHT USING (xe) 
DTR>01 BOAT. 
DTR> 03 TYPE. 





DTR> 06 MANUFACTURER PIC X(10) Cer) 
DTR> QUERY-NAME IS BUILDER. 
DTR> 06 MODEL PIC X(10). 

DTR> 03 SPECIFICATIONS (Cer) 

DTR> QUERY-NAME SPECS. 

DTR> 06 RIG PIC X(6). Ce) 

DTR> 06 LENGTH-OVER-ALL PIC XXX Cer) 
DTR> QUERY-NAME IS LOA. 

DTR> 06 DISPLACEMENT PIC 99999 (er) 
DTR> QUERY-HEADER IS "WEIGHT" 
DTR> EDIT~STRING IS 22,229 Cx) 
DTR> QUERY-NAME IS DISP. 
DTR> 06 BEAM PIC 99. 

DTR> 06 PRICE PIC 99999 Cr) 

DTR> EDIT-STRING IS $$,S$S$S. 
DTR> 3; (Cer 


The SHOW record-name command (Section 4.3) will allow 
you to confirm that a record definition has been 
created as you planned. This is a good practice 
because it is important to keep up-to-date copies of 
the record definitions, in case they should be lost or 
damaged during operation. 
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7.1.2 Defining the Domains--DEFINE DOMAIN 


For each domain, there can be only one record type as defined by the 
DEFINE RECORD command described in Section 7.1.1. However, different 
domains may reference the same record type, if desired. In this 
section you will learn how to define a domain. 


Purpose 


Format 


FOR THE DATA ADMINISTRATOR 


DEFINE DOMAIN 


' This command defines a domain of one kind of record. — 


Without this definition, which is kept in the Data 
Dictionary, no references can be made to the records. 


DEFINE DOMAIN domain-nme-l USING rec-nme-1 ON rms-file-spec-l ; 


Requirements 


Restriction 


Prompts & 
Responses 


Effects 


1. 


Ze 


5. 


You must supply a domain-name, and it must be 
unique. 


You must also provide a record name for a_ record 
that has been or will be defined to exist in this 
domain. 


You must provide an RMS-1ll file specification that 


identifies the device and file name and extension 
where the domain will reside, or at least exist, 
during operations. 


You must not use any of the keywords (Section 3.11) 
for your domain or record names. Furthermore, you 
must not duplicate previously defined domain, 
record, or procedure names when establishing the 
new domain name. The record name must uniquely 


identify its record definition. 


You must terminate the command with a semicolon. 


Use only unique names for domains and records. 


You must not use the DEFINE DOMAIN command in a 
procedure definition. 


None. 


Provided you have chosen a unique domain name _ for 
the domain, your new definition will be placed in 
the Data Dictionary. 


A password table (Section 7.2) will be created for 
this resource and your UIC will be entered with 
full access privileges (RWEMC). 


If the domain name you choose is not unique, your 
command will be rejected. (To modify an existing 
domain definition, you must first delete the old 
version with the DELETE command (Section 7.1.4), 
and then issue a new DEFINE DOMAIN command. See 
also the alternate method suggested in Section 
Fede] 


Example 


Hint 
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The following example defines the domain YACHTS, using 
the record called YACHT, from the file YACHT.DAT. 
Observe that the domain name is the plural form, 
YACHTS, while the record name is singular. This makes 
the two names unique, although the difference is 
somewhat subtle. 


DTR>DEFINE DOMAIN YACHTS USING YACHT ON Cer ) 
DTR>YACHT.DAT; 


The SHOW domain-name command (Section 4.3) will confirm 
that a domain definition has been created as you 
planned. 
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7.1.3 Defining a Procedure -- DEFINE PROCEDURE 


Before any user can invoke a procedure, it must be defined and 
2 catalogued. One command is used to do this: DEFINE PROCEDURE. 
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DEFINE PROCEDURE 


Purpose 


Format 


Requirements 


Restrictions 


Prompts & 
Responses 


Effects 


This command creates a procedure definition that is 
automatically catalogued in the Data Dictionary. This 
procedure definition becomes available immediately to 
you and any other user. It remains available until it 
is deleted by means of the DELETE command. 


DEFINE PROCEDURE procedure-name-l 


; DATATRIEVE-11 commands and statements 


END-PROCEDURE ; 


1. You must supply a procedure name, which must 
conform to the rules for names in Section 3.7. 


2. You may specify one or more DATATRIEVE commands or 
statements, optionally separated by semicolons. 


3. The end of the procedure definition is signalled by 
an END-PROCEDURE statement. 


None. 


You must not include any of the following commands that 
require access to the Data Dictionary: READY, SHOW, 
DEFINE RECORD, DEFINE DOMAIN, DEFINEP, DELETE, DELETEP, 
or SHOWP. 


You cannot nest DEFINE PROCEDURE commands. In other 
words, do not attempt to create a procedure within a 
procedure. 


None. 


1. The procedure, consisting of all the commands’ and 
statements you specify, is automatically catalogued 
by name in the Data Dictionary. 


2. Any comments you specify in the definition are not 
catalogued. 


3. A password table (Section 7.2) will be created for 
this resource and your UIC will be entered with 
full access privileges (RWEMC). 


Examples 


Hints 
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The following example shows how to create a 
procedure definition that will produce a report of 
yacht types for the YACHTS domain every time the 
procedure is invoked. 


DTR>DEFINE PROCEDURE YACHT-TYPE-REPORT (2 ) 
DTR>REPORT YACHTS SORTED BY ASC RIG, BUILDER, LOA (zr) 
DTR>SET REPORT-NAME="YACHTS GROUPED BY TYPE"; 
DTR>PRINT RIG, BUILDER, LOA, DISP, BEAM, PRICE; 
DTR>AT BOTTOM OF RIG PRINT COUNT (zr) 

DTR>REPORT END; Czer_) 

DTR>FINISH; 

DTR>END-~PROCEDURE; 


Test your procedures as DATATRIEVE-11 commands 
before you create and catalogue the formal 
definitions. This permits you to debug them first. 
Otherwise, you may create a definition, try it, 
find it doesn't work, and be faced with deleting it 
so that you may reenter the entire piece of code 
again. You cannot simply change a line of code in 
the definition. If a definition is in error, it 
Must be first removed, then reentered,. 

See also the editing technique suggested in Section 
7.1 as an alternative. 
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7.1.4 Deleting a Previous Definition -- DELETE 


Before you can redefine any domain, record, or procedure, you are 
required to delete the existing definition. This requirement helps 
ensure that definitions are not mistakenly corrupted, and lends 
support to the requirement that only unique names may be used. 


Purpose 


Format 


Requirements 


Restriction 


Prompts & 


Responses 


Effects 


Examples 


FOR THE DATA ADMINISTRATOR 


DELETE 


This command deletes a previous definition of either a 


domain, procedure, or record from the Data Dictionary. 
Once the item is removed, no user can _ successfully 
reference it. 


domain-name-1 
DELETE { record-name-1 [(password-str-1)]; 
procedure-name-1 


1. You must’ supply your choice of either a 
domain name, a record name, or a procedure name. 


2. You must terminate the command with a semicolon. 


3. You must possess C(ontrol) access privileges’ for 
the named resource. This will be determined from 
your UIC or the optional password you may supply. 
See Section 7.2 for more information on passwords. 


The name specified for the domain, record, or procedure 
must match a name defined in the Data Dictionary. 


You must possess C(ontrol) access privileges. 


You must not include the DELETE command in a procedure 
definition. 


None. 


1. The definition of the record, domain, or procedure 
is removed from the Data Dictionary. When dealing 
with records and domains, note that only the 
definition is removed. There is no effect on the 
physical file: neither the file nor its records 
are deleted. Only the ability to reference the 
data through DATATRIEVE-1l is lost, at least until 
such time as new definitions are provided. 


2. The password table for the named resource is also 
removed from the Data Dictionary. 


The following example deletes the definition of the 
domain called YACHTS, assuming that your UIC possesses 
C privileges. 


DTR>DELETE YACHTS; 


Hints 
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The following example illustrates how to remove _ the 
definition of the yacht record from the Data Dictionary 
using a password that has been accorded C privileges. 


DTR>DELETE YACHT (SUNNY-DAY) ; 


The last example illustrates how you might delete the 
definition of the procedure called PRICE-PER-POUND. 


DTR>DELETE PRICE-PER-POUND; 


If critical definitions are accidentally deleted with 
this command, you can replace them with the DEFINE 
command. 


However, this brings up another advantage of using 
indirect command files for all your definitions, as 
suggested in Section 7.1. Restoring a lost definition 
can be as easy as 


DTR>@PRODF1 


if the definition is stored in a command file such as 
PRODF1.CMD, in this case. 
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7.2 DATA PROTECTION FEATURES 


The protection of data within DATATRIEVE-11 is accomplished through 
two independent mechanisms: the protection systems of RMS-1l1 and 
those within DATATRIEVE-ii itseif. The DATATRIEVE-1ll user’ can 
regulate access to domains, records, and procedures through access 
requirements recorded with the definitions in the Data Dictionary. 


Before you can learn the commands that direct and control the security 
features of DATATRIEVE-11, you must learn some basic concepts of the 
design. 


7.2.1 Two Types of Lock 
This security system employs two different types of lock: 


PW (Passwords) -- character strings of up to ten characters that 
the user must employ with certain commands (for 
example, SUNNY-DAY and FAIRWINDS). 


uIct (or PPNT) account numbers -- numbers known to the operating 
system that DATATRIEVE-1i can check, that the user 
need not’ specify. Thus, this is the default 
lock-type that is tested when required (for example, 


[305,305] and [*,*]). 
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These locks and keys are maintained on a domain, record, and procedure 
basis. That is, each resource has its own password table identifying 
the password strings or user account numbers that may have access to 
the resource. Furthermore, this table tracks the type of access that 
May be granted the user whose key satisfies the key and _ lock-type 
requirements. 


7.2.2 Five Types of Privileges 


The types of access are called the user's privileges. Thus, even 
though you may be allowed to modify the YACHTS domain, your co-worker 
Steve may only be permitted to read the records in the same domain. 
The types of privileges are defined in Table 7-1. 


7.2.3 Password Table Structure 


Figure 7-1 illustrates the password table structure using a _ possible 
example for the YACHTS domain. Each sequential line is a password 
table entry. 


There will never be a vacancy in the sequential table entries. 
DATATRIEVE-ll processing of the DEFINEP and DELETEP commands ensures 
this. 


~ UIC is the User Identification Code specification referred to by 
Many operating systems, while PPN is the "Project Programmer Number" 
as referred to by RSTS/E. Both refer to the user's disk directory and 
are expressed syntactically as [m,n] where m and n may be integers or 
an asterisk (*). In this manual the term UIC will be adopted. 
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Table 7-1 
Privilege Codes 


Privilege 
Code Meaning 


R(ead)-- User can only retrieve this resource. 


E(xtend)--User can only add records to this 
resource, 

1 (odify)--User i hange records in 
this resource. 


W(rite)-- User can do all of tthe above (retrieve, 
change, and add), and can also erase records. 


C(ontrol)--User can issue the data protection 
commands: DELETEP, DEFINEP, and SHOWP, as well as 
DELETE. 





There can be from zero to five privileges granted per lock-type and 
key entry. However, since a W privilege grants R, E, and M privileges 
anyway, there will seldom be more than four privileges per entry. 


The number of entries in each table is unrestricted and all entries 
are dynamically allocated. 


Sequence Lock 
Number Type Key Privileges 


PW FAIRWINDS CW 
PW SUNNY-DAY 


W 
UIC [304,303] "H” 
PW STAR-KEY R 
UIC [305,305] CREM 
UIC [301,314] C 
vIC [*,305] REM 





Figure 7-1. Example of Password Table Structure 


7.2.4 Creating and Maintaining Password Tables 

The password tables are automatically started and given a single entry 
at resource definition time. This entry identifies the creating user 
(by UIC) and permits the creator the full set of privileges (REMWC), 
for this resource. 


One of the Data Administrator's major responsibilities is to define 
the additional password table entries for each resource. These 
additional entries are created by means of the DEFINEP command. They 
are Maintained by the DELETEP and DEFINEP commands. Since the 
authorized Data Administrator also needs to obtain printouts of the 
tables for review, the SHOWP command is designed for this purpose. 


Entries are created or deleted one at a time, except when the entire 
table is erased, The password table far any resource is erased 
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whenever that resource is deleted by means of the DELETE command. 
(See Section 7.1.4.) 
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These table creation and maintenance commands are so important to’ the 
protection of the data that only users with the C(ontrol) privilege 
will be allowed to invoke them. 


7.2.5 Password Table Processing 
Whenever there is a question of access to a domain, record, or 
procedure, the password table for that resource is examined. Access 
privileges are checked for any of the following commands: 

@ READY 

e SHOW domain-name 


e SHOW record-name 


@ SHOW procedure-name 


e@e DEFINEP 
@ DELETEP 
@ SHOWP 

@ DELETE 


Password tables are processed in a standard fashion that has important 
implications for the table entry designer. The rules are summarized 
below and illustrated by the flowchart in Figure 7-2. 


1. Users who are considered "privileged" by their operating 
system because they have received project codes lower than 8, 
are automatically given the C(ontrol) access privilege. They 
May receive additional privileges as a result of the next two 
steps that otherwise apply to less privileged users. 


2. Table entries are searched sequentially looking for the first 
hit. Thus, if a particular user qualifies for access under a 
number of possible lock-type and key combinations, the access 
privileges granted will be the first one(s) encountered. 


3. The comparison of keys is directed by the lock-type 
specification in the table (not by the user's password 
specification or default UIC). If the table entry calls for 
a PW (password) lock-type, the user's command is checked for 
inclusion of a password that matches. If the table entry 
calls for a UIC, the user's UIC is automatically checked. 


The combined effect of these three rules is that even if the user has 
a password and specifies it with the command, it will serve no purpose 
if the user qualifies for access under a UIC type of table entry that 
DATATRIEVE-11 encounters first. 


FOR THE DATA ADMINISTRATOR 


User requested 
READY, DELETE, 
DEFINEP, DELETEP, 
SHOWP, or 

SHOW resource-nme-1 





DATA PROTECTION 
CHECK ROUTINE 






Determine UIC 
and save it 













Is 











this user Yes Give user the 
privileged C privilege as 
? a minimum 
(*) No 
Any (more) No 


table entries for 
this resource? 


Access denied 










Read next 
table entry 







Equal 
or 
in range 





What 
is table entry's 
lock-type? 


VIC Compare 


the UIC keys 












Did 
user specify a 
password? 


Not 


equal Assume user has- 






Equal 


Compare the 
password keys 


the privileges 
in the table 














READ EXTEND 
Does Does 
user have No user have No 
R, M, or W Eorw 
privilege? privilege? 
i Yes | Yes 










Not equal 
or 


not in range (4) 


Does 
user have 
C privilege? 















Access granted 








DELETE 


DEFINEP Yes 





















SHOWP 
DELETEP SHOW resource-nme-1 
Analyze Does 
access request user have 
by command any privilege? 


No 


READY 


What 
was access mode 
user specified? 


MODIFY WRITE 










Does 
user have 
Ww 
privilege? 


Does 
user have 
M or W 
privilege? 














Yes Yes 


{ Access granted } 
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The following examples test a few user attempts to gain access to’ the 
YACHTS domain against the sample table in Figure 7-l. 





The user of account [304,303] issues a SHOW YACHTS command. No 
password is given. The first possible hit occurs on the third table 
entry and user [304,303] is denied access privileges. (However, if 
this user knew either of the two passwords FAIRWINDS or SUNNY-DAY, 
access would have been granted. This would probably defeat the intent 
of the designer who intended to lock that account out.) 





The user of account [301,305] issues a READY YACHTS WRITE command. No 
password is given. The first possible hit occurs on the seventh table 
entry. However, W is not one of the privileges granted in the table, 
so the request is denied. 






Se. 


The user of account [301,314] issues a READY YACHTS (STAR-KEY) 
command. The default access requested is SHARED READ. There is a hit 
on the fourth entry because the password matches and this’ user 
receives retrieval privileges. 


7.2.6 Coding the Table Entries 


Table 7-2 summarizes the types of privileges required to use certain 
important commands. The table may help you construct and then 
mentally check your password table designs prior to putting them into 
effect. As you code each entry you may find it helpful to think in 


the following terms: 


-.. to enable this user to issue these commands, 
-».» give these privileges... 


Where the table shows two privileges that afford the use of the same 
command, you may choose to give either one. However, keep in mind 
that the W privilege is more all-encompassing. Don't give W 
privileges to the user you want to be able to MODIFY but not ERASE, 
because although W permits MODIFY commands, it also permits ERASE 
commands. Instead, give M privileges. For this reason, X's under W 
in Table 7-2 are shown in parentheses. 


Work your way down the table, and then throw away any duplicate 
privileges. Whenever you have WR, WM, or WE combinations, you may 
simplify them to just W. Likewise, MR is redundant; use just M. 
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Table 7-2 
Privilege Requirements By Command 


Command Permits Also Privilege Required 
Soe of 1) 


one =r ne 








DELETEP 


READY WRITE ERASE 
MODIFY, 
STORE, 

REPEAT STORE, 
and retrieval 
commandst 













READY MODIFY MODIFY 


and ee a 
commandst 


READY EXTEND STORE, 
REPEAT STORE 

READY READ retrieval | 
commandst 


+ The retrieval commands are FIND, SELECT, SHOW CURRENT, SORT, and 
PRINT. Parentheses indicate give W privileges with care because W 
permits a number of other capabilities also. 











7.2.7 Design Guidelines for Password Tables 


The following guidelines are offered as suggestions. They are not 
restrictions. 


walt iu 


low-numbered entries. This w 
passwords to gain access. 


1. Place any UICs that will be 4a among the 


es 
cessful use of 


2. Place password entries with maximum privileges (such as C and 
W) next. This could avoid users intended to gain the most 
powers from matching the less restrictive requirements and 
gaining fewer privileges instead. 
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Place the least restrictive entries, such as any UICs 
containing an asterisk or any PWs having commonly known 
passwords, near the end of the table. As a general rule, you 


_ Should grant these users the fewest privileges... .. 


If you will grant any privileges to all users through the UIC 
designation [*,*], place it as the very last entry. It is 
meaningless to have entries that follow this one since they 
will never be reached. It is dangerous for this form to 
precede the vital entry with C privileges because then no one 
can print, change, or even delete the table, unless they 
receive C privileges due to having project codes less than 8. 


SUMMARY NOTE 


While these data protection features are 
relatively sophisticated and powerful, 
they are not impervious to systematic 
attacks by determined outsiders. They 
can prevent browsing and discourage a 


number of accidental errors by 
unqualified users. They can best be 
applied in the overall context of 
careful data management by the 


installation at large. 


To summarize, if the installation as a 
whole follows tight security 
regulations, these features will augment 
those practices. 
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7.2.8 Adding Entries to the Password Table -- DEFINEP 


The user who defines a resource is often the only one to use it so 
there is no requirement to add entries to the password table. 
However, whenever it can be anticipated that a resource will be 
shared, consideration should be given to _ protecting the resource 
through additional password table entries. The command that permits 
the addition of entries is DEFINEP. 


Purpose 


Format 


Requirements 
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DEFINEP 


This command allows you to add one entry to the 
password table for whatever resource you name. The 
resource may be a domain, record, or procedure. 


DEFINEP resource-nme-1l [(password-str-1)] segq-number, 


lock-type-1, key-l, privilege-str-1l 


1s 


2. 


You must supply a resource name that identifies 
either a defined domain, record name, or procedure. 


Password-str-l is your personal password enclosed 
in parentheses. If you do not provide a password, 
your UIC will be used to check that you have C 
privileges. 


You must also supply a sequence number that 
identifies the table entry in the password table 
that you will be creating. This sequence number 
must be an integer. 


q 


alid lock-types 


tT 


You must specify the lock-type. 
are either PW or UIC. © 


You must specify the key that unlocks the 
lock-type. That is, if the lock-type is given as 
PW, you must identify the valid password. 
Passwords are character strings of one to ten 
characters. 


If the lock-type is given as UIC, then you must 
identify which UIC will be permitted access. The 
UIC format is: 


* * 
[ 1,l ] 


f 
integer-l integer-2 


The square brackets in this case are required 
elements. They differ from syntax brackets in that 
they are part of the command input line. 


You must specify the privileges to be granted. 
Choose from any or all the characters in Table 7-1. 
If you wish this particular user to receive no 
privileges, you may specify "6", where the quotes 
are required. 


You must have C(ontrol) access privileges. 


The named resource must have been previously defined. 


Restriction 


Prompts & 
Responses 


Effects 


Examples 


Hint 
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You must not include the DEFINEP command in a procedure 
definition. 


None, unless you specify an asterisk (*) for the 
optional password. This will cause the prompt: 


PLEASE SUPPLY PASSWORD: 


to appear. In this prompt mode your password 
specification is not echoed on your terminal -- for 
greater password security. 


l. If you are deemed to have C(ontrol) privileges, a 
table entry will be created in the password table 
of the resource you name. This table resides in 
the Data Dictionary. 


2. If the sequence number you specify either: 


a. already exists -- the new entry takes its place 
and it and all higher numbered entries are 
moved ahead by one, or 


b. is greater than the last existing one plus’ one 
-~-the number is ignored and the entry becomes 
the next sequential one. For example, there 
are five entries when you specify a sequence 
number of nine. Your new entry becomes’ the 
sixth one, not the ninth. 


The following example illustrates how to add the fourth 
password table entry for the YACHTS domain table. 


DTR>DEFINEP YACHTS (FAIRWINDS) 4,PW,STAR-KEY,R (®t ) 


The following example illustrates how to create the 
sixth password table entry for the same YACHTS domain 
table. 


DTR>DEFINEP YACHTS (FAIRWINDS) 6,UIC,[302,314],C 


To avoid errors, always obtain a current copy of the 
password table prior to making any additions. (See 
Section 7.2.10, SHOWP.) Due to the manner of table 
processing, the sequence of a particular entry can 
greatly affect the efficacy of the rest of the entries. 
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7.2.9 Deleting a Password Table Entry -- DELETEP 


While maintaining a password table, you may need to delete one or more 
entries. The DELETEP command permits this. However, if your goal is 
to delete the entire table, you should use-~the proper -form of ~the 
DELETE command instead. 


DELETEP 


Purpose 


Format 


Requirements 


Restriction 


Prompts & 
Responses 


Effects 
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This command deletes one table entry from the password 
table of the named resource. The resource may be a 
domain, record, or procedure. 


DELETEP resource-nme-l [(password-str-1)] seq-number 


1. You must supply a resource name that is either a 
defined domain, record, or procedure. 


2. Password-str-l is your personal password enclosed 
in parentheses. If you do not provide a password, 
your UIC will be used to check that you have 
C(ontrol) privileges. 


3. You must supply a sequence number that identifies 
the specific table entry you wish to delete from 


its password table. This sequence number must be 
an integer. 


1. You must have C(ontrol) access privileges. 


2. The named resource must have been previously 
defined. 


You must not include the DELETEP command in a procedure 
definition. 


None, unless you specify an asterisk (*) for the 
optional password. This will cause the prompt: 


PLEASE SUPPLY PASSWORD: 
to appear. In this prompt mode your password 


specification is not echoed on your terminal -- for 
greater password security. 


1. If you are deemed to have C(ontrol) privileges, the 
table entry will be reviewed for deletion. 


2. Deletion of the table entry will occur under both 
of the following conditions: 


a. it exists, and 


b, it is not the only remaining table entry that 
can grant C(ontrol) privileges. 


Examples 


Hints 
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The following example illustrates how to delete the 


fourth password table entry in the YACHTS domain table.. 


DTR> DELETEP YACHTS (FAIRWINDS) 4(C®) 


To delete the sixth password table entry: 


DTR> DELETEP YACHTS (FAIRWINDS) 6 Cer) 


To avoid errors, 
password table 
Section 7.2.10.) 
to delete has 
number. 


always obtain a current copy of the 
prior to making any deletions. (See 
Always check that the entry you wish 
not been moved to a different sequence 


You can only delete one entry at a time. To delete the 


entire table, 
resource. 


use the DELETE command and name the 


FOR THE DATA ADMINISTRATOR 


7.2.10 Printing a Password Table -- SHOWP 


A special command is provided to enable users with C privileges to 
view the password table for any given named resource. It is important 
that this be done before every change. Printed copies of the table 
should be either very carefully guarded or destroyed when not in use. 


Purpose 


Format 


Requirements 


Prompts & 
Responses 


Effects 


Example 


Hint 
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SHOWP 


“This command allows you to obtain a printout of a 


password table on your terminal device. 


SHOWP resource-nme-1 [(password-str-1)] 


1. You must supply a resource name that is either a 
defined domain, record, or procedure. 


2. Password-str-l is your personal password enclosed 
in parentheses. If you do not provide a password, 
your UIC will be used to check that you have 
C(ontrol) privileges. 


1. You must have C(ontrol) access privileges. 


2. The named resource must have been previously 
defined. 


You must not include the SHOWP command in a procedure 
definition, 


th 
™~ 


ere! an acta 


wae wen wt 


fy xr 
will cause the following prompt 


None, unless 


aiteGceing 4 yo = Spe 
optional password. Th 
to appear: 


PLEASE SUPPLY PASSWORD: 


ek (*) far +h 
~ A a 


is mw Ss ee diend Nor oh he 


In this prompt mode your password specification 
is not echoed on your terminal -- for greater password 
protection. 


If you have C(ontrol) privileges, and _ the named 
resource exists, its password table is printed in its 
entirety on your terminal device. 


The following example illustrates how to print the 
password table for the YACHTS domain, assuming the 
password FAIRWINDS has been accorded C(ontrol) 
privileges. 


DTR>SHOWP YACHTS (FAIRWINDS) 


If your terminal provides hard copy, take care not _ to 
walk away and leave the printout open to _ public 
inspection. Given a copy of the table and this manual, 
most users could gain access to the resource. 
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7.3 RESTRUCTURING DATA 


It is possible to restructure data with DATATRIEVE-11. In this 
section you will learn a possible technique. In the context of this 
Manual, "restructuring" refers to selecting data fields from the 
records in one or more files (or subsets of those files) to create 
records of an altered format in a new file. The new record, as you 
will see in the example, may also include other data fields that were 
not part of the original file(s). 


The general technique consists of providing record and domain 
definitions for the new file through the DEFINE RECORD and DEFINE 
DOMAIN commands. Once you ready all the domains, and the domain that 
will receive the data must be readied for WRITE or EXTEND access, you 
simply issue a combination of FOR and STORE to cause the transfer of 
data. The example below will illustrate this. 


In this exanple the familiar YACHT record is providing the bulk of the 
data. Assume that for each YACHT record in existence now a new, 
shorter record is desired that will contain the same builder, model, 
and price data, but will provide a new field for the quantity. This 
new field will be called the NUMBER-IN-STOCK. None of the other data 
items, such as rig, beam, length-over-all, and weight, is desired. 
The DATATRIEVE~-11l record and domain definitions could be formulated as 
shown below. (It is also necessary that you define the NEW-YACHTS 
file through RMS-ll and your operating system. The file may be 
defined as either sequential or indexed sequential, but not relative.) 


DEFINE RECORD NEW-YACHT USING 
01 BOAT. 
05 BUILDER PIC X(15). 
05 MODEL PIC X(10). 
U5" PRICK PIC 9 (5). -_ 
05 NUMBER-IN-STOCK PIC 9(3). 


DEFINE DOMAIN NEW-YACHTS USING NEW-YACHT ON SUMMARY.YCT; 


Observe that the BUILDER field in the new record has been defined to 
include five more characters than the original record definition 
(Section 7.1.1). However, the PRICE and MODEL fields are identical in 
both record definitions. 


The following command sequence will cause the selected data in each 
record in the YACHTS domain to be copied into a new record in the 
NEW-YACHTS domain, in an altered format. 


READY YACHTS 
READY NEW-YACHTS WRITE 
FOR YACHTS 
STORE NEW-YACHTS USING 
BOAT = BOAT 
EXIT 


Note that the specification of BOAT, the Ol-level number item forces 
all the subordinate-level number items to be included in the STORE 
function. Only items having matching names in the record definitions 
(for example, BUILDER, MODEL, and PRICE) are processed. Observe that 
the match for BUILDER occurs by virtue of the QUERY-NAME. As this 
implies, matches are not restricted to the primary name of the field. 
Since the new BUILDER field is larger, it will be padded (in this 
case, with blanks at the right). Furthermore, since no field in the 
Old definition can be found to match NUMBER-IN-STOCK, that data item 


will be set to zero in each of the new records. Figure 7-3 
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illustrates this process graphically. 


Had you wished instead to create new records for a subset of the old 
records, you. could have used... an._appropriate.._ record | 
selection expression in the FOR statement. For example, if you knew 
that this branch of the marina would only carry the less costly boats 


(priced under $35,000), you could have modified the FOR statement as 
follows: 


FOR YACHTS WITH PRICE < 35000 


The result of such a clause would be to create a subset of the 
original file of records. 


In this one-for-one process, 


YACHTS NEW-YACHTS 
















ALBIN VEGA SLOOP 27 5070 8 18600 ALBIN VEGA 


















| 79 SLOOP 26 4200 10 17900 ALBIN 29 17900 0 


| ALBERG 37MKIi KETCH 37 20000 12 36951 | | ; ALBERG 37MKI!I 36951 8) | | 


| BUILDER MODEL RIG’ LOA DISP BEAM PRICE BUILDER MODEL PRICE AQTY | 1] 






Figure 7-3 Illustrating a Simple Case of Restructuring 
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APPENDIX A 


SAMPLE DATATRIEVE-11 SESSION 


The following session was run under an IAS Operating System. 


Pos: RUN DTR 

123252333 

Hetetrieve: DEC Query and Rerort System 
Version? VO1.00» 22-NOV-77 

Tyre HELF for hele 


IrOAME 
DTR>!SAMPLE DATATRIEVE SESSION 


DTR> ! 
QTRSDEFINE RECORD! BOOK USING 
NTR: O1 BOOK-TITLE. — 


DTR> O03 TITLE PIC X(22). 

DTR> 03 FIRST-AUTHOR. 

QTR 046 LAST-NAME-AUTHI FIC X¢(15). 
NTR? 04 FIRST-NAME-AUTHI PIC X, 
DTR> 03 FUBLISHER FIC X(15). 

QTR> 03 CATEGORY PIC 99. 

DTR> 03 PRINT-DATE PIC 99. 

NTR> O03 LOCATION PIC xX. 

DTR> O03 LOANEN-TO FIC X¢10). 

NTR> O3 TYFE PIC X. 

DTR> 3 

DTR> ! 


UTR=SHOW BOOKS 
RECORD BOOK 
USING 
O61 ROOK-TITLE. 
O03 TITLE PIC X(22). 
03 FIRST-AUTHOR. 
06 LAST-NAME-AUTHI PIC X(15). 
O06 FIRST-NAME-AUTHI PIC X- 
O03 FUBLISHER FIC X(15). 
63 CATEGORY FIC 99. 
O03 PRINT-DATE FIC 99. 
03 LOCATION FIC X. 
O03 LOANED-TO FIC X¢(10). 
O03 TYFE FIC X. 


¥ 
TR ! 
QTR> /TEFINING THE DOMAIN 
DTR> ! 
DTRSDEFINE DOMAIN BOOKS USING BOOK ON BOOK.DAT;: 
NTR> ! 
DTR>SHOW BOOKS: 
DOMAIN EBOOKS 
USING BOOK ON BOOK.DAT; 


SAMPLE DATATRIEVE-11 SESSION 


DTRe ADD FOUR NEW BOOK RECORTS 


DTR> ! 
DTRSREADY BOOKS WRIT 


Es 
i 


NTRSREFEAT 4 STORE BOOKSs 


Flease surely value 
Please surrlys value 
Please surprly value 
Please surely value 
Please suprly value 
Please surrly value” 
Plesse surely value 
Please surely value 
Please surrly value 
Please surely velie 
Please surely value 
Please surrly value 
Please surely value 
Please surrly value 
Please suprly value 
Flease surrly value 
Please surrly value 
Plesse surrly velue 
Please surrly value 
Flease surrly value 
Flease surprly value 
Please surely value 
Please surprly value 
Flease surely value 
Flease surrly value 
Please surrly value 
Please surrly value 
Please surely value 
Flease surrly value 
Flease surrly value 
Please surrly value 
Flease surrly value 
FPlease surrly value 
Please surrly value 
Flease surely value 
Please surely value 
NTRS! 

UTRSFING COMFSCI IN 
3 records found] 
QTRSSELECT 1 


for 
for 
for 
for 
for 
for 
for 
for 
for 
far 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 
for 


TITLE? SUPERMONEY 
LAST-NAME-AUTH1:3 SMITH 
FIRST-NAME-AUTHI: A 
PUBLISHER! RANIIOM HOUSE 
CATEGORY? 15 
FRINT-DATE? 72 
LOCATION: I 

LOANED-TO? 

TYPE? H 

TITLE? CURTATIA 
LAST~NAME-AUTHI? CHRISTIE 
FIRST-NAME-AUTHI? A 
FUBLISHERS FOCKET BOOKS 
CATEGORY? 13 
FRINT-IATE? 746 
LOCATION: I 

LOANED-TO$ 

TYPE? F 

TITLE? THE ART OF LOVING 
LAST-NAME-AUTH1? FROMM 
FIRST-NAME-AUTHI? E 
PUBLISHER? HARFER & ROW 
CATEGORY? 11 
PRINT-IATE? 62 
LOCATION? I 

LOANED-TO? 

TYPE? F 

TITLE? HEART OF DIARKNESS 
LAST-NAME-AUTH1? CONRAD 
FIRST-NAME-AUTH1: J 
FUBLISHER? W.W. NORTON 
CATEGORY: 99 
PRINT-DATE? 43 
LOCATION: I 

LOANED-TO; 

TYPE? F 


BOOKS WITH CATEGORY EQUAL O93 


QTRSFRINT SRIF 2»"THESE BOOKS ARE IN THE COMPUTER SCIENCE CATEGORY*»SKIF 2 THEN FOR 


DYR=COMFSCI PRINT TITLEs 


FIRST-AUTHORsFUBLISHER sFRINT-DATE »— 


QDTRELOCATION(C"LOC*/*T=IN*/°O=OUT") ys TYFEC* TYPE" /"FP=FAPER */*H=HARII ) 


THESE BOOKS ARE IN T 


TITLE 


NIGITAL LOGIC CIRCUI 
INTRO. TO DATABASE S 
BASIC DIGITAL ELECTR 


NTR»! 
DTRSiQEFINE A& REFORT 
OTR! 
NTREDEFINE FROCENURE 


DTRSREFORT BOOKS WITH LOCATION EQ "0" SORTED BY LOANEDI-TOs 


NTRSSET REFORT-NAME 
DTR?SET COLUMNS-FAGE 
NTRSPRINT LOANED-TO 
DTRSREFORT ENDS 


DTRDEND-~PROCERURE 3 


HE 


TS 
Ys 
ON 


WRITER SEQUENCE THAT WILL IDENTIFY 


COMPUTER SCIENCE CATEGORY 


LAST FIRST 

NAME NAME 

AUTH1 AUTH 
LIBES +S) 
DATE c 
RYAN R 


ON-LOAN-REFORT 


= "KOOKS ON LOAN" 


BO 
("BORROWED / "RY" ) yLAST-~NAME-AUTHI» TITLE» CATEGORY: TYFEs 


FUBLISHER 


HAYDEN BOOK CO. 
ADDISON-WESLEY 
TAR BOOKS 


BROOKS ON 


LOC TYPE 
PRINT I=IN P=PAFER 
DATE O=OUT H=HARD 
75 0 F 
74 I H 
735 0 F 
LOAN 


LAST-NAME-AUTH1 


a 


SAMPLE DATATRIEVE-11 SESSION 


DTR=INEFINE @ REPORT WRITER SEQUENCE TO LIST ALL THE FAPERBACKS 
DIRS! 

DTREDEFINE PROCEDURE FAPERBACK-REFORT 

UTR>REFORT BOOKS WITH TYPE = "P* SORTED BY ASC FIRST-AUTHOR? 
DTR>SET REFORT-NAME = “*FAPERBACKS": COLUMNS-PAGE = 803 





DTRZPRINT LAST-NAME-AUTHis TITLE, LOCATION, CATEGORY? 

DTR2AT ROTTOM OF REFORT FRINT SKIF 2*/COL 25*"TOTAL PAPERBACKS! "»COUNTsSKIP 29- 
DTRECOL 25» "AVERAGE AGE OF. BOOKS! *»(77 - AVERAGE FPRINT-IIATE) 
DTReREFORT END 

DTRZEND-FROCEDURE 3 

OTR?! 

DTR=IDEFINE A SECOND RECORD TYFE THAT WILL BE USED TO DECODE EACH 
DTR>!CATEGORY NUMBER 

DTRS! ; 

DIRSDEFINE RECORD CAT-DECONER USING 

NTR= O01 BOOK-TITLE. 


DTR> 03 TITLE FIC X(22), 

NTR> O03 CATGRY FIC X(15). 

DTR> $ 

NTRS! 

DTRSDEFINE DOMAIN CAT-DECODE USING CAT-DECODER ON CATGRY.DAT$ 
OTR?! 


DTRSiDEFINE A FROCEDRURE TO TRANSLATE THE NUMERICALLY CODED CATEGORIES TO 
DTR+!ENGLISH EQUIVALENT 

NTR}! 

DTRS! 

DTRSDQEFINE FROCEQURE TRANSLATE-CATEGORY 

DTRSFOR BOOKS 

DTRSIF CATEGORY=05 THEN STORE CAT-DECODE BEGIN TITLE=TITLEsCATGRY 
BTRSIF CATEGORY=0% THEN STORE CAT-DECODE BEGIN TITLE=TITLEsCATGRY 
QTR?IF CATEGORY=11 THEN STORE CAT-IECODE REGIN TITLE=TITLE#CATGRY 
QTReIF CATEGORY=13 THEN STORE CAT-DECOIE KREGIN TITLE=TITLEsCATGRY 
NTRSIF CATEGORY=15 THEN STORE CAT-DECODE REGIN TITLE=TITLE#CATGRY 


"ENGL"SEND ELSE 
"CMF SC"FEND ELSE 
"PSYCH" SEND ELSE 
*FICT* SENT ELSE 


"ECONOM’ SENT ELSE 


HoH Uo it 


DTRZABORT "CAN’T DECODE THIS. CATEGORY -- "!CATEGORY 
DTRPEND-FROCEDURE? 

QTR! 

DTRe!FPRINT THE PAPERBACK ANID ON-LOAN-REFORTS 

QTR! 


DTRSREADY BOOKS WRITE 
QYTR=FINE BOOKS 
Ci2 records found] 


DTRSSELECT 1 
DTR> 3 PAPERBACK-REPORT 3 
PAFERBACKS 2-DEC-77 
PAGE 1 
LAST 
NAME 
AUTH TITLE LOCATION CATEGORY 
CHRISTIE CURTAIN I 13 
CONRAD HEART OF DARKNESS I 99 
FROMM THE ART OF LOVING I 11 
ILG CHILID BEHAVIOR 0 11 
LIBES DIGITAL LOGIC CIRCUITS 0 0? 
RYAN BASIC DIGITAL ELECTRON 0 0? 
SHEEHY FASSAGES ‘ Q 11 
TOTAL FPAFERBACKS? 7 
AVERAGE AGE OF BOOKS: 7 


DTR» ¢ON-LOAN-REFORT 


SAMPLE DATATRIEVE-11 


SESSION 


BOOKS ON LOAN 2-HEC-77 
PAGE 1 
LAST 
BORROWED NAME 
BY AUTHI TITLE CATEGORY TYFE 
RB. BORROWE HOGINS THE STRUCTURE OF WRITI 05 H 
IZ. SHOCKER RYAN BASIC DIGITAL ELECTRON Oo? F 
H. KANTWRI HODGES HARBRACE COLLEGE HNDRK 05 H 
J. WURSTKI ILG CHILD) BEHAVIOR ii F 
N. BLUEAGE SHEEHY PASSAGES ii F 
Te TOOKIT LIBES DIGITAL LOGIC CIRCUITS oO? P- 


| 


OTR: 
NTR> |! TRANSLATE EACH CATEGORY ANT SAVE IT IN THE CAT-IECODER RECORD 


DTR> ! 


DTR2 READY CAT-DECODE WRITE 


DTR>FIND BOOKS 


£12 records found 
QTR: 


NTR: t TRANSLATE~CATEGORY 


ABORT? 


CAN‘’T DRECODE THIS CATEGORY -- 99 


Execution terminated by "ABORT" statement 


NTR 


DTR>!NOW PRINT THE NEW RECORDS JUST CREATED 


Re! 


LTR FIND CAT-DECODESSELECT isFRINT ALL OF CAT-DECONEsS 


Eid records found] 


TITLE 


DIGITAL LOGIC CIRCUITS 
INTRO. TO DATABASE SYS 
THE STRUCTURE OF WRITI 
ROGET’S THESAURUS 
CHILD BEHAVIOR 

BASIC DIGITAL ELECTRON 
HARBRACE COLLEGE HNIVBK 
PASSAGES 

SUPERMONEY 

CURTAIN 

THE ART OF LOVING 


DTR:>! BEFORE LEAVING THIS SESSION» 


DTR>! 
DITR>DELETE BOOK? 
DTR>DELETE BROOKS: 


CATGRY 


CMF SC 
CMP SC 
ENGL 
ENGL 
FSYCH 
CMP SC 
ENGL 
PSYCH 
ECONOM 
FICT 
PSYCH 


DELETE ALL THESE TEMPORARY DEFINITIONS 


OTR> DELETE ON-~LOAN-REPORT? 
DTR>DELETE PAPERBACK-REFORT 3 


DTR>DELETE 
DTR> DELETE 
OTRYQELETE 
DTRREXIT 
RYE 


123277227 


CAT-DECONEs 


Bizet? 28K CFU? 


TRANSLATE-CATEGORY 3 
CAT-DECODERs 


0.58 


APPENDIX B 


SUMMARY OF DATATRIEVE-11 COMMANDS AND STATEMENTS 





DEFINE DOMAIN domain-name-1l USING record-name-l ON rms-file-spec-1 ; 


f 


DEFINE PROCEDURE procedure-name-1l 


} DATATRIEVE statements and commands 


END-PROCEDURE; 
_DEFINE RECORD..record=name=1 USING data-def-1 [data-def-2...].; 


fs 


DEFINEP resource-nme-1l [(password-str-1)] seg~number, lock-type-1,key-1, 
privilege-str-1l 


Ss Soom 
DELETE( record-name-1l [(password-str-1)]; 
procedure-name-1 . 

DELETEP resource-nme-1 [(password-str-1)] segq-number 
ERASE [ALL [OF rse]}) 

EXIT 

FIND domain-name-1 [WITH condition] 

FIND CURRENT [WITH condition] 

FIND record-selection-expression 

FINISH [domain-name-1 [,domain-name-2...]] 

HELP [ADVANCED] [command-name-1[,command-name-2...]] 
MODIFY [ALL] [field-name-1 [,field-name-2...]] [oF rse] 


print [ALL] [print-list-1] [or rse] [on Gai } 


* ,prompt-name-1 





READ 
SHARED MODIFY 

READY domain-name~1 {(password-str-1)] | bxonscreD | WRITE 
EXCLUSIVE EXTEND 


RELEASE collection-name-1 [,collection-name-2...] 


SUMMARY OF DATATRIEVE~11 COMMANDS AND STATEMENTS 





FIRST 
NEXT 

SELECT | LAST [collection-name-1] 
value-exp-l 





SHOW show-item-1 [,show-item-2...] 
where the show items are chosen from the following list: 


(PROCEDURES ) 
DOMAINS 
COLLECTIONS 
RECORDS 
ALL 
CURRENT 
READY 
procedure-name-1 [(password-str-1)] 
domain-name-1 [(password-str-2) 
record-name-1 [(password-str-3)] 
collection-name-1 


SHOWP resource-1 [(password-str-1)] 
sort [collection-name-1] BY sort-key-1 [,sort-key-2...] 
where the sort-keys assume the following form: 
ASC [ENDING] 
DESC[ENDING] | field-name-1 
INCREASING 
DECREASING 


STORE domain-name-1 [USING statement-1] [VERIFY USING statement-2] 





field-name-1 value-exp-1 


field-name-1 field-name-2 

ABORT value-exp-l 

BEGIN statement-1 [;statement-2...] END 
DISPLAY value-exp-1l 

FOR rse-1 statement-l 

IF condition THEN statement-1 [ELSE statement-2] 
REPEAT value-exp-1 statement-1l 


statement-1 THEN statement-2 


SUMMARY OF DATATRIEVE-11 COMMANDS AND STATEMENTS 










fld-name-1l 
PAGE PRINT summry-item-1 [,summry-item-2...] 
"REPORT [| © 


AT See z 
BOTTOM 
(Table 5-2 lists all the summary items.) 

PRINT detail-item-1 [,detail-item-2...] 

REPORT [rse] [ON file-spec-1] 

REPORT END 

SET parameter-1 [,parameter-2...] 


where the parameters are chosen from the following list: 


REPORT-NAME = report-name 


MAX-LINES = integer-l 
MAX-PAGES = integer-2 
NUMBER 

NO-NUMBER 

DATE = ["string-1"] 
NO-DATE 

LINES=PAGE = integer-3 
COLUMNS-PAGE = integer-4 





where the record selection expression (rse) assumes the following form: 
CALL ‘7 CURRENT + 


al, 0 
FIRST n | [collectn-name-2 IN] po tne nane- 3), (unre conditn] 
domain-name-1 


[SORTED BY key-1[,key-2...]] 
where each sort-key is in the form: 
ASC [ENDING] 
DESC [ENDING] | field-name-1 


INCREASING 
DECREASING 


Item Format 


ot SE erent 


field-name-1l 
















collectn-name-1.field-name--2 


"character-string" 


integer-1 


- value-exp-1l 


( value-exp-2 ) 


+ 
value-exp-3 I value-exp-4 


/ 





Contents of this field in the CURRENT 
record! are evaluated and used. 


Contents of this field in the CURRENT 
record! of the named collection are 
evaluated and used. 


The character string is used as given, 
unless the context forces it to be 
treated as a number’. 


A string of digits interpreted as a 
decimal number. 


The resultant value is the negation of 
the value of value-exp-l. 


Causes the evaluation of the enclosed 
value expression to occur prior to 
that of any other value expression 
with which it appears. 


Interpreted as the arithmetic result 
of the operation on the two values ex- 
pressed by the value expressions. 





Remarks 


Uses CURRENT record! of CURRENT collec- 
tion, so both must exist and contain a 
field with this name. 


Be sure to supply a period (.) as a 
connector. The field named must exist 
in the records of the named collection. 
The collection must be established and 
have a CURRENT record’. 


Any characters may be used except the 
carriage return, line feed, or CTRL % 
(*Z). To include a quotation mark, use 
two successive quotation marks. 


Take care when using character-strings 
for value-exp-1l: they are changed into 
numbers. 


The rules of precedence for arithmetic 
operations hold (unless you use paren- 
theses to force certain operations to 
occur first): multiplications (*) and 
divisions (/) precede additions (+) 
and subtractions (-), working left-to- 
right. 


(continued on next page) 
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Item Format Description 


value-exp-5 | value-exp-6 Creates a new character string by com- 
bining the two character strings given 
for value-exp-5 and value-exp-6. 


MAX Computes? your choice of the maximum, 

MIN minimum, average, or total, respective- 
AVERAGE ly of this value expression for all 

TOTAL , records (in the CURRENT collection, by 
default). If the OF clause is used, 
then the computation can occur on your 
choice of the named collection, the 
named domain, or the CURRENT collection, 
and they can be further restricted by 
the rest of the expression. 


value-exp-7 [OF rse] 


ee a Permits the specification of the value 
Ce are at execution time. Has special impor- 
tance in procedures. Prompt-name-1 
should be the name you want 
DATATRIEVE-11 to use to prompt you 

to supply a value. 


COUNT [OF rse] Computes the number of records in the 
object of the record selection express- 
ion. 





Remarks 


Special caution should be used with 
numbers. The result maintains a. 
left-to-right pattern. For example, 
"ABC"! "DEF" produces "ABCDEF", | 
"12"1"934" produces "12034", but. 
12!034 produces 1234. 


DATATRIEVE-11 prints the message 
PLEASE SUPPLY VALUE FOR prompt-name-1: 
and waits for your response before it 
processes the command in which this 
value expression occurs. (Examples 
occur in Sections 4.11 and 4.13.2.) 


The default is the number of records 
in the CURRENT collection. 





‘The CURRENT record is the record the collection cursor identifies. The collection cursor can only be moved to 


a record by the SELECT command, which is discussed in Section 4.6. 


2value expressions are treated as numbers in the SELECT command, in the FIRST n clause of the record selection 
expression, and when subject to arithmetic operators (+, -, *, and /) or computations for maximum, minimum, 
total, and average. Thus, these are not appropriate places for the alphanumeric character string. 
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Operator 


EQUAL B,C, [OR] D 
= B,C, (OR] D 


Format/Example Meaning 
> A>B True if A is greater than B 
| GT A GT B 
GREATER-THAN A GREATER-THAN B 
| GE A GE B True if A is greater than or equal to B 
GREATER-EQUAL A GREATER-EQUAL B 
t< A<B True if A is less than B 
LT A LT B 
LESS--THAN A LESS-THAN B 
LE A LE B True if A is less than or equal in value to B 
LESS—EQUAL A LESS-EQUAL B 
A EQ B True if A equals B 
EQUAL A EQUAL B 
A=B 
A EQ B,C, [OR] D True if A equals any of the three values, B, C, or D 
A 
A 
NOT-EQUAL A NOT-EQUAL B True if A does not equal B 
NE A NE B 
BT A BT B [AND] C True if the value of A falls in between the range of values of B through 
BETWEEN A BETWEEN 3 [AND] C Cc, inclusive 
BOOL-A AND BOOL-B True if the values of the Boolean expressions BOOL-A and BOOL-B are both 
PRICE>10000 AND true 


BUILDER EQ "SEAWORTHY" (ret) 


NOT BOOL-A True if the value of the Boolean expression BOOL-A is false 
NOT PRICE>10000 Caer) 


BOOL-A OR BOOL-B True if either of the Boolean expressions BOOL-A or BOOL=B is true 
MODEL="43K" OR MODEL="49K" 


(BOOL=A) True if BOOL-A is true. The parentheses force the evaluation of this 
(BEAM<12 AND LOA BT 20 AND 35) Boolean first. Note that BOOL-A can be a compound Boolean, and this is a 
means of grouping Booleans in case the normal precedence rules* would not 

produce the desired effect. 

Note ; 

The character A above represents a field name, while B, C, and D are value expressions (as described in Section 4.5.1). 











*Normal precedence rules require evaluation of expressions with NOT first, followed by expressions with AND, followed by 
expressions with OR. 
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SUMMARY OF DATATRIEVE-11 COMMANDS AND STATEMENTS 


Element Function 


Specifies a class of data 
items to be printed 

from the record. 
Modifiers are 
explained below. 





Defauit 


All the fields 
in the record 














field-name-1 [modifiers] 



















A value to be in- 
serted. See Section 
4.5.1. Modifiers 

are explained below. 


value-exp-1 [modifiers] 













Causes n horizontal 1 space 
spaces between entries 


on each line. 





SPACE [hn] 




















If n is omitted, a 
single tab is assumed 


va 


TAB [n] Introduces as many 
tab characters into the 
print line as spec- 


ified by n. 











Advances across the 
horizontal line to column 
n. Note: n must 

not be less than 1 or 
more than the page 
width. 

















n 


| Moves n blank li 
| ahead to start a 


new 

line. Printing starts in | 
column 1, unless another 

element modifies the pos- 

ition further. 
Begins a new print None 
page. Printing starts in 

column 1, unless another 

element modifies the 

position further. 


NEW-PAGE 





("header-1" [/"header-2"...]) Specifies a character Headers are composed 
String See Section 3.8. of the field-name 
to be printed on definitions from the 
successive lines over record definitions 
the immediately 
preécéding field-name 
or value-expression. 
Specification of a 
hyphen for the header 
indicates no header is 
desired. 


USING edit-string Imposes the character- Uses the edit-string in 


istics of this edit- the record definition, if 
string on the preceding any. Otherwise consid- 
field or value expression. ers the field's PICTURE 
Edit-strings must observe string. 

COBOL Rules (Appendix E). 


NOTE 


DATATRIEVE-11 restricts the column width 
to 132 characters. It sets tabs 
automatically at every eighth column. 
Thus, if the print position is column 10 
and DATATRIEVE encounters a TAB 2 
specification, the new position will be 
column 24. 


ABORT 
ADVANCED 
ALL 

AND 

ASC 
ASCENDING 
AT 
AVERAGE 


BEGIN 
RETWEEN 


ro Ae ee 


BOTTOM 

BT 

BY 
CHARACTER 
COL 
COLLECTIONS 
COLUMN 
COLUMN-HEADER 
COLUMNS-PAGE 
COMP 

COMP-1 
COMP-2 
COMP-3 
COMP-5 
COMP—6 
COUNT 
CURRENT 
DATE 
DECREASING 
DEFINE 
DEFINEP 
DELETE 
DELETEP 
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DESC 
DESCENDING 
DISPLAY 
DOMAIN 
DOMAINS 
EDIT-STRING 
ELSE 

END 
END-PROCEDURE 
EQ 

EQUAL 

ERASE 
EXCLUSIVE 
EXIT 

EXTEND 

FILL 

FIND 

FINISH 
FIRST 

FOR 

GE 
GREATER-EQUAL 
GREATER-THAN 
GT 

HELP 

IF 

IN 
INCREASING 
Is 

JUSTIFY 
LAST 

LE 

LEADING 


LESS-EQUAL 
LESS~THAN 
LINES-PAGE 
LT 

MAX 
MAX-LINES 
MAX-PAGES 
MIN 

MODIFY 

NE 

NEW-~ PAGE 
NEW-SECTION 
NEXT 

NO 

NO-DATE 
NO-NUMBER 
NOT 
NOT-EQUAL 
NUMBER 

OF 

ON 

OR 

PAGE 

PIC 
PICTURE 
PRINT 
PROCEDURE 
PROCEDURES 
PROTECTED 
PW 
QUERY-HEADER 
QUERY-NAME 
READ 





READY 
RECORD 
RECORDS 
RELEASE 
REPEAT 
REPORT 
REPORT-HEADER 
REPORT-NAME 
SELECT 
SELECTIVE 
SEPARATE 
SET 
SHARED 
SHOW 
SHOWP 
SIGN 

SKIP 

SORT 
SORTED 
SPACE 
STORE 

TAB 

THE 

THEN 

TOP 

TOTAL 
TRAILING 
UIC 

USAGE 
USING 


VERIFY 
WITH 
WRITE 
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DATATRIEVE-11 MESSAGES (ALPHABETICALLY) 


NOTES 


Errors marked here by (SPR) should not 
occur. If you receive one of these 


messages, use a Software Performance 
Report to notify DIGITAL. Be sure to 
include all pertinent output. 





ree 
these messages denotes 
will occur in the actual message that | 
will identify troublesome items. 


IS AN UNKNOWN NAME 
IS NEITHER A COLLECTION NOR A 
CLAUSE NOT RECOGNIZED 
IS AN UNKNOWN SET OPTION 
IS NOT A KNOWN DICTIONARY ELEMENT TYPE 
IS NOT A PROCEDURE 
IS NOT THE NAME OF A READIED DOMAIN 
"=" EXPECTED, "---" ENCOUNTERED 
"AT ---" IS INNOVATIVE, BUT, ALAS, UNKNOWN 
"AT" CONDITION PREVIOUSLY SPECIFIED 
"SET ---" IS UNKNOWN 
"THEN" EXPECTED, PROCEEDING ANYWAY 
SCLOSE FAILED 
SCONNECT FAILED 
SCREATE FAILED 
SDELETE FAILED 
SDISCONNECT FAILED 
SDISPLAY FAILED 
SFIND FAILED 
SFREE FAILED 
SFREE OPERATION ISSUED BUT NO BUCKET WAS LOCKED 
S$GET FAILED 
SINIT NEVER ISSUED 
SINITF FAILED 
SOPEN FAILED 
SPUT FAILED 
SREWIND FAILED 
SUPDATE FAILED 
SWAIT ERROR ON WORK FILE 
SWAIT FAILED 
--- IS NEITHER A DOMAIN NOR COLLECTION 
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--- IS BEYOND HELP 

--- IS NOT A DOMAIN NAME 

--- IS NOT A VALID RECORD NAME 

ACCESS DENIED TO DICTIONARY RESOURCE "---" 


ACCESS TO FILE "---" DENIED BY OPERATING SYSTEM 
ARITHMETIC OVERFLOW DURING CONVERSION 
ASSIGNMENT TO DATA TYPE NOT IMPLEMENTED YET (SPR) 


ATTEMPT TO ADD RECORD TO MIDDLE OF SEQUENTIAL FILE 

ATTEMPT TO DELETE LAST PRIVILEGE ENTRY 

ATTEMPT TO DIVIDE BY ZERO, RETURNING -1l AS VALUE 

ATTEMPT TO EXTEND AN AREA CONTAINING AN UNUSED EXTENT 

ATTEMPT TO RELEASE BAD BLOCK (SPR) 
ATTEMPT TO UPDATE KEY FIELD W/O CHANGE ATTRIBUTE 


AUXILIARY OUTPUT FILE CLOSED 
BAD "IS" NODE (SPR) 
BAD ALLOCATION QUANTITY 

| 


BAD ALN FIELD IN ALLOCATION XAB 
BAD AOP FIELD IN ALLOCATION XAB 
BAD AREA NUMBER IN LAN FIELD IN XAB 
BAD BUFFER ADDRESS (SPR) 
BAD CHANNEL NUMBER (LCH) IN FAB 
BAD COD FIELD IN XAB 
BAD EDIT CHARACTER (SPR) 
BAD ELEMENT ("---") IN QUERY-HEADER 
BAD FILE NAME STRING 
BAD IAD FIELD IN ALLOCATION XAB 
BAD IAN FIELD IN XAB 
BAD ISI FIELD IN TERMINAL RAB 
BAD LOC FIELD OF XAB 
BAD LOCK TYPE, DICTIONARY DAMAGED (SPR) 
BAD NAM FIELD IN FAB 
BAD ORG FIELD OF FAB 
BAD POS FIELD IN XAB 
BAD PRINT COLUMN SPECIFIED IN REPORT LINE 
BAD RAB 
BAD RAC FIELD IN RAB 
BAD RAT FIELD IN RAB 
BAD RBF FIELD IN RAB 
BAD RECORD FILE ADDRESS IN RAB 
BAD RECORD FORMAT ON MAG TAPE 
BAD RECORD IN SEQUENTIAL FILE 
| BAD RFM FIELD IN FAB 
BAD ROP FIELD 
BAD RRV RECORD IN INDEXED FILE; FILE MAY BE CORRUPT 
BAD RSZ FIELD IN RAB DURING SPUT OR SUPDATE 
BAD SHR FIELD IN FAB 
BAD SIZ FIELD IN XAB 
BAD UBF FIELD IN RAB 
BAD UIC SPECIFICATION 
BAD VALUE FOR COLUMNS-PAGE 
BAD VOL FIELD IN XAB 
BAD XAB FIELD IN FAB 
| BEGINNING OF FILE DETECTED DURING $SPACE 
| BLOCK LENGTH IN FAB OR RAB IS INCORRECT 
BUCKET SIZE FIELD EXCEEDS MAXIMUM 
| BUCKET SIZE FIELD IN XAB EXCEEDS MAXIMUM 
| BUFFER IN USE (SPR) 
CAN'T ACCESS DICTIONARY FOR WRITE 
| CAN'T CONNECT SECOND RAB TO SEQUENTIAL FILE 
CAN'T ERASE RECORD FROM SEQUENTIAL FILE (DOMAIN "---") 
CAN'T OPEN COMMAND FILE 
CAN'T READY DICTIONARY; DICTIONARY POSSIBLY CORRUPT 


OCnqzwim eEmMAnNE RECNDNH TA DMCA YPOHTAMTVUE BATT (NOMATN-~ TH — 
| VAN 2 DAUD REC AY AN AIO ROowALAVG Pau (YUAN FHA) 


CAN'T TAKE MIN, MAX, AVERAGE, OR TOTAL OF ZERO OBJECTS 


DATATRIEVE-11 MESSAGES (ALPHABETICALLY) 





CENTRAL STORAGE POOL EXHAUSTED 
CLOSE FUNCTION FAILED (MUST BE RSTS/E) 


COLLECTION NOT IN SYSTEM COLLECTION LIST (SPR) 
COLUMN ASSIGNMENT NOT FOUND (SPR) 
COLUMNS-PAGE--VALUE- IS--TOO -LARGE 4 
COMMAND "---" IS UNKNOWN 


COMMAND FILE NESTING LIMIT EXCEEDED 

COMMAND FILE SYNTAX ERROR 

COMPARISON FOR DATA TYPE NOT YET IMPLEMENTED (SPR) 
COMPILER STORAGE POOL EXHAUSTED, REQUEST ABANDONED 

CONTROL ACCESS NOT ALLOWED 


CONVERSION NOT YET IMPLEMENTED (SPR) 
COULDN'T FIND HASH TABLE NODE FOR REMOVAL (SPR) 
DATA TYPE NOT YET IMPLEMENTED FOR SORT (SPR) 


DEVICE FULL: CAN'T CREATE OR EXTEND FILE 

DEVICE IS WRITE LOCKED 

DEVICE NAME SYNTAX ERROR IN "---" 

DEVICE NOT READY 

DEVICE POSITIONING ERROR 

DICTIONARY ELEMENT "---" IS ALREADY IN USE 
DICTIONARY ELEMENT "---" NOT FOUND 

DICTIONARY IS DAMAGED, PLEASE "QUIT" IMMEDIATELY! 
DICTIONARY OBJECT IS TOO LARGE 

DICTIONARY OPERATION ALREADY IN PROGRESS 
DICTIONARY OPERATION IS IN PROGRESS 

DICTIONARY RECORDS OUTSTANDING (SPR) 
DICTIONARY NAME SYNTAX ERROR IN "---" 

DICTIONARY NOT FOUND FOR FILE "---" 


DOMAIN --~ HAS NOT BEEN DEFINED 

DOMAIN --- NOT PROPERLY READIED FOR ERASE 

DOMAIN --- NOT PROPERLY READIED FOR MODIFY 

DOMAIN --- NOT PROPERLY READIED FOR STORE 

DOMAIN NOT FOUND IN SYSTEM DOMAIN LIST (SPR) 


DUPLICATE FIELD BREAK SPECIFIED FOR --- 
DUPLICATE OR INVALID SIGN SPECIFIED 


END OF FILE 

END OF HEADER STRING NOT FOUND (SPR) 
END OF PRIMARY INPUT FILE, SESSION TERMINATING 

EOF POSITIONING FAILED (SPR) 
ERROR IN FILE PROLOGUE: FILE IS CORRUPT 

ERROR ON PRIMARY INPUT FILE 

ERROR WHILE READYING FILE PROLOGUE 

ERROR WHILE WRITING PROLOGUE 

EXECUTION FAILED 

EXECUTION TERMINATED BY "ABORT" COMMAND 

EXECUTION TERMINATED BY OPERATOR 

EXPANDED STRING AREA IN NAM BLOCK TOO SHORT 

EXPECTED A NUMBER, ENCOUNTERED "- 

EXPECTED "'S" IN QUALIFIED SET NAME, ENCOUNTERED "---" 

EXPECTED ";" AFTER DELETE, ENCOUNTERED "---" 

EXPECTED "=" IN SET STATEMENT, ENCOUNTERED "---" 

EXPECTED "IS" POINTER NODE (SPR) 
EXPECTED "LEADING" OR "TRAILING", ENCOUNTERED "---" 

EXPECTED CL BLOCK (SPR) 
EXPECTED CN BLOCK (SPR) 
EXPECTED CN OR ST NODE (SPR) 
EXPECTED CO BLOCK (SPR) 
EXPECTED CO OR OD BLOCK (SPR) 
EXPECTED COLLECTION NAME, ENCOUNTERED "---" 

EXPECTED COMMA OR END OF STATEMENT, ENCOUNTERED "---" 

EXPECTED DD BLOCK (SPR) 
EXPECTED END OF DELETEP STATEMENT, ENCOUNTERED "---" 


EXPECTED END OF REPORT STATEMENT, ENCOUNTERED "---" 
EXPECTED END OF STATEMENT AFTER DOMAIN DEF., ENCOUNTERED "---" 





DATATRIEVE-11 MESSAGES (ALPHABETICALLY) 


EXPECTED END OF STATEMENT AFTER PROC. DEF., ENCOUNTERED "---" 
EXPECTED END OF STATEMENT AFTER RECORD DEF, ENCOUNTERED "---" 
EXPECTED END OF STATEMENT OR "COMMA", ENCOUNTERED "---" 
EXPECTED END OF STATEMENT, ENCOUNTERED "~--" 

EXPECTED FD BLOCK 

EXPECTED FIELD NAME BLOCK 

EXPECTED FIELD NAME, ENCOUNTERED "---" 

EXPECTED FS BLOCK 

EXPECTED HT BLOCK 

EXPECTED IS OR CN BLOCK 

EXPECTED IS PRINT OBJECT 

EXPECTED IS, FD, OR CN BLOCK 

EXPECTED LK BLOCK, DICTIONARY DAMAGED 

EXPECTED LOCK TYPE (PW OR UIC), ENCOUNTERED *---" 

EXPECTED NAME NODE 

EXPECTED NN BLOCK 

EXPECTED NUMBER IN SET STATEMENT, ENCOUNTERED "---" 
EXPECTED NUMBER, ENCOUNTERED NON-DIGIT 

EXPECTED OCTAL NUMBER, ENCOUNTERED "---" 

EXPECTED PERIOD FOLLOWING FIELD DEFINITION, ENCOUNTERED "---" 
EXPECTED PRIVILEGE LIST, ENCOUNTERED "---" 

EXPECTED PT BLOCK, DICTIONARY DAMAGED 

EXPECTED RD BLOCK 

EXPECTED READY MODE, ENCOUNTERED "--- 

EXPECTED RELATIONAL OPERATOR (EQ, ETC.), ENCOUNTERED "---" 
EXPECTED RO BLOCK 

EXPECTED RS BLOCK 

EXPECTED ST BLOCK 

EXPECTED STATEMENT, ENCOUNTERED "---" 

EXPECTED STATISTICAL BLOCK 

nian ae VL BLOCK 

FIELD "--~-" NOT INCLUDED IN SORT ORDER 

FIELD NAME "---" IS AMBIGUOUS 

FILE "---" ALREADY EXISTS 

FILE "---" IN COMPATIBLE USE BY ANOTHER USER 

FILE "---" NOT FOUND 

FILE COULD NOT BE SPOOLED, REISSUE COMMAND 


FILE 
FILE 
FILE 


EXPIRATION DATE NOT REACHED 
EXTEND FAILURE 
HEADER CONTAINS BAD DATE/TIME INFORMATION 


FILE NAME SYNTAX ERROR IN "---" 
FILE OPEN FAILED, DOMAIN NOT READIED 


FILE 
FILE 


READ ERROR 
TYPE SYNTAX ERROR IN "-~--" 


FILE WRITE ERROR 


FILES-11 
FILES~11 
PILES-11 
FILES-11 
GET-PAGE 


ACP COULD NOT MARK FILE FOR DELETION 
ACP ENTER FUNCTION FAILED 

ACP FIND FUNCTION FAILED 

ACP REMOVE FUNCTION FAILED 

FAILED 


HASH TABLE ENTRY FAILED 
HEADER SEGMENT NOT RECOGNIZED 
HEADER STRING EXHAUSTED 
I/O OPERATION PENDING FOR FILE 


ILLEGAL ASSIGNMENT TO GROUP 
COMPUTATION PICTURE 


ILLEGAL 


DATA ITEM 
ON FIELD "---" 


ILLEGAL DUPLICATE 
ILLEGAL OPERATION 
ILLEGAL PICTURE ON --- 

ILLEGAL PLACEMENT OF MINUS SIGN, IGNORING SIGN 
ILLEGAL SIGN ON COMPUTATIONAL DATA ITEM 
INCONSISTENT RECORD LENGTH FOR SORT 

INCORRECT "REPORT END" STATEMENT 


KEY Va ALUE 


(SPR) 
(SPR) 


(SPR) 
(SPR) 
(SPR) 
(SPR) 
(SPR) 
(SPR) 


(SPR) 
(SPR) 


(SPR) 
(SPR) 


(SPR) 
(SPR) 
(SPR) 


(SPR) 
(SPR) 


(SPR) 
(SPR) 
(SPR) 
(SPR) 


(SPR) 


ARERR sme en PR Ne Ric 
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INDEX BUCKET CHECK-TYPE MISMATCH; FILE CORRUPT 
INDEX NOT INITIALIZED 


INDEX TREE ERROR; INDEXED FILE IS CORRUPT 
INTERNAL DATA STRUCTURE IS CORRUPTED 

“INTERNAL INDEX DESCRIPTOR SPACE EXHAUSTED 
INTERNAL RMS-11 ERROR (PLEASE NOTIFY DEC) 


INVALID AREA NUMBER IN DAN FIELD OF XAB 

INVALID COLUMN HEADER 

INVALID COLUMN HEADER ("---") 

INVALID COMBINATION OF NO DUPLICATES AND CHANGE 


INVALID 


DISK ADDRESS 


INVALID FILE ID 

INVALID FILE OPTIONS 

INVALID IFI FIELD IN FAB 

INVALID KEY OF REFERENCE IN RAB 

INVALID OPERATION IN AST 

INVALID OVERPUNCHED SIGN, ASSUMING +0 FOR DIGIT 
INVALID REAL ADDRESS 


INVALID REPORT STATEMENT ("---") 
INVALID USAGE TYPE "---" 
KEY --- DOES NOT MATCH ANY FIELD 


KEY BUFFER ADDRESS IS ZERO 

KEY SIZE IS ZERO 

KEY SIZE ZERO OR NEGATIV 

LINE SKIP LIMITED EXCEEDED 

LOCK TYPE NOT KNOWN, DICTIONARY DAMAGED 

LOGICAL CHANNEL IS BUSY 

MAG TAPE IS NOT ANSI LABELED 

MAX NUMBER OF KEYS EXCEEDED 

MAXIMUM NUMBER OF HEADER LINES HAS BEEN EXCEEDED 
MAXIMUM RECORD SIZE IS ZERO, AND RECORD IS FIXED OR RELATIVE 
MISSING PICTURE OR EDIT STRING 

MORE TABS SPECIFIED THAN EXIST FOR LINE WIDTH 
MULTIPLE DECIMAL POINTS IN "---" 

MULTIPLE DETAIL LINES SPECIFIED IN REPORT (LIMIT OF ONE) 
NAME TOO LONG FOR DICTIONARY USAGE 

NEGATIVE VALUE ASSIGNED TO UNSIGNED DATA ITEM (---) 
NESTED DICTIONARY ACCESSES ARE NOT ALLOWED 
NESTED DICTIONARY ACCESSES NOT PERMITTED 

NO BUFFERS AVAILABLE, REQUEST ABANDONED 

NO COLLECTION FOR SELECT 

NO CONTEXT FOR ERASE 

NO CONTEXT FOR MODIFY 

NO CONTEXT FOR PRINT 

NO CONTEXT HAS BEEN ESTABLISHED FOR FIELD NAME "---" 
NO CURRENT RECORD 

NO DATA ITEMS MATCHED FOR GROUP ASSIGNMENT 

NO PICTURE SPECIFIED ON ELEMENTARY FIELD "---" 
NO PRIMARY KEY SPECIFIED FOR INDEX FILE 

NO RECORD SELECTED, PRINTING WHOLE COLLECTION 

NO REPORT-NAME SPECIFIED 

NO SELECTED RECORD FOR MODIFY 

NO SORT ORDER FOR REPORT 

NODE TYPE NOT RECOGNIZED 

NODE TYPE NOT YET IMPLEMENTED 

NON-DIGIT IN STRING "---", IGNORING CHARACTER(S) 
NOT A RECOGNIZED NODE TYPE 

NOT VALID FAB 

NULL STATEMENT LIST 

NUMERIC VALUE TOO GREAT FOR DATA TYPE (OVERFLOW) 
OPEN FOR FILE "---" FAILED 

OPERATING SYSTEM COULD NOT ACCESS FILE "---" 
OPERATING SYSTEM COULD NOT CREATE FILE "---" 
OPERATING SYSTEM ERROR DURING SCLOSE 





(SPR) | 


(SPR) 


(SPR) 


(SPR) 


(SPR) 


(SPR) 
(SPR) 


(SPR) 


(SPR) 
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OPERATION NOT DECLARED AT OPEN TIME 
OPERATION NOT SELECTED IN ORGS MACRO 
OUT OF SEQUENCE SPUT FOR INDEXED FILE 
OVERFLOW DURING MULTIPLICATION 


PAGE LEFT LOCKED (SPR) 
PAGE NOT IN USE (SPR) 
PERMANENT STORAGE POOL EXHAUSTED, REQUEST ABANDONED (SPR) 


PRINT OBJECT TOO LARGE FOR LINE WIDTH 

PRIVATE BUFFER POOL ADDRESS NOT ON DOUBLE WORD BOUNDARY 

PRIVATE BUFFER POOL SIZE NOT MULTIPLE OF 4 

PRIVILEGE SEQUENCE NUMBERS START AT 1, THANK YOU 

PROTECTION TABLE ELEMENT DOESN'T EXIST 

RE-READY FAILED, DOMAIN "---" AUTOMATICALLY FINISHED 

READ ERROR ON FILE HEADER ATTRIBUTES 

READ ERROR ON WORK FILE 

RECORD "~--" HAS NOT BEEN DEFINED 

RECORD HAS BEEN DELETED 

RECORD IDENTIFIED IS NON-POSITIVE 

RECORD IDENTIFIED IS OUT OF RANGE 

RECORD INDENTIFIED BY INDEX DOESN'T EXIST 

RECORD NOT IN CORE (SPR) 
RECORD NUMBER OUT OF RANGE FOR COLLECTION 

RECORD STREAM ALREADY ACTIVE 

RECORD TOO BIG 

RECORD TYPE ALREADY IN USE 

RELATIVE RECORD ALREADY EXISTS 

REPEAT COUNT IS NOT REASONABLE 

REPORT FORMATTING CLAUSE OUT OF CONTEXT 

REQUEST FOR BLOCK OF ZERO LENGTH (SPR) 
REQUESTED ACCESS TO "~--" DENIED 

REQUESTED COLLECTION NAME "---" IS IN USE 

RETRN CALLED AFTER ERROR (SPR) 
RMS DYNAMIC MEMORY HAS BEEN PSERUSTED 

RMS WON'T RELEASE BLOCK (SPR) 
RMS WON'T RELEASE BLOCK AFTER SCLOSE (SPR) 
RMS WON'T RETURN BLOCK TO SORT (SPR) 
RO BLOCK IS ALREADY CONNECTED (SPR) 
RUN TIME STORAGE POOL EXHAUSTED, REQUEST ABANDONED 

SEARCHING FOR SEMI-COLON 

SELECTED RECORD HAS BEEN PREVIOUSLY DELETED 

SORT ALREADY IN PROGRESS (SPR) 
SORT DEVICE INPUT ERROR 

SORT DEVICE OUTPUT ERROR 


SORT END OF FILE RECORD ERROR (SPR) 
SORT END OF STRING RECORD ERROR (SPR) 
SORT ERROR, COLLECTION RELEASED (SORRY) (SPR) 
SORT FOUND RECORD LARGER THAN EXPECTED (SPR) 
SORT INPUT OPEN FAILED 

SORT KEY ADDRESS ODD (SPR) 
SORT OUTPUT OPEN FAILED 

SORT RECORD ADDRESS ODD (SPR) 
SORT RECORD EXCEEDS MAXIMUM SIZE (SPR) 
SORT RECORD SIZE NOT POSITIVE (SPR) 
SORT SCRATCH RECORD TOO LARGE (SPR) 
SORT SUBROUTINES CALLED OUT OF ORDER (SPR) 


SORT WORK SPACE EXHAUSTED 

SPACE EXHAUSTED IN DICTIONARY ELEMENT 

SPLIT KEYS ARE NOT SUPPORTED, KEY IGNORED 

SPOOLER QUEUE OPERATION FAILED (SPR) 
SPOOLER REQUEST OPERATION FAILED, DON'T WORRY 

STACK SPACE EXHAUSTED 

STACK SPACE EXHAUSTED DURING ASYNCH OPERATION 

STATEMENT NOT IMPLEMENTED YET (SPR) 
SYMBOL "---" IS ALREADY IN USE; DOMAIN --- CANNOT BE READIED | 


a a ae 


D-6 
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SYNTAX ERROR DURING DOMAIN DEFINITION 
SYNTAX ERROR DURING RECORD DEFINITION 


SYNTAX ERROR IN CREATEP COMMAND 

| SYNTAX ERROR IN. FILE. VERSION.NUMBER.... 
SYNTAX ERROR IN PASSWORD SPECIFICATION 
SYSTEM DIRECTIVE ERROR 
TARGET BUCKET LOCKED 


TOO FEW SCRATCH FILES FOR SORT (SPR) 
TOO MANY ITEMS FOR SINGLE REPORT LINE 
TOO MANY SCRATCH FILES FOR SORT (SPR) 


TRUNCATION DURING ASSIGNMENT 

UNMATCHED PARENTHESIS IN ARITHMETIC EXPRESSION 

UNMATCHED PARENTHESIS IN BOOLEAN EXPRESSION 

UNMATCHED PARENTHESIS IN PICTURE STRING 

UNRECOGNIZED NAME "---" 

UNRECOGNIZED OPERATOR (SPR) 
UNRECOGNIZED OR UNIMPLEMENTED STATEMENT TYPE (SPR) 
UNTERMINATED QUOTED STRING 

VALUE TOO LARGE 


WORK FILE $CONNECT FAILED (SPR) 
WORK FILE $WAIT FAILED (SPR) 
WORK FILE CREATE FAILED (SPR) 
WORK FILE PAGE NUMBER OUT OF RANGE (SPR) 


| WORK FILE SPACE EXHAUSTED 

WORK FILE WRITE FAILED 

| WRITE ERROR ON FILE HEADER ATTRIBUTES | 
XAB'S NOT IN PROPER ORDER 

| [--- RECORDS FOUND] | 
[1 RECORD FOUND] | 
[LOOKING FOR "="] 
[LOOKING FOR "BY" OR SORT LIST] 
[LOOKING FOR "FIRST", DOMAIN NAME, OR COLLECTION NAME] 
[LOOKING FOR "SET" OPTION] 
[LOOKING FOR "SET" VALUE] 
[LOOKING FOR A MATCHING PARENTHESIS] 

[LOOKING FOR A VALUE EXPRESSION] 

[LOOKING FOR ASSIGNMENT STATEMENT (S) ] 

[LOOKING FOR BOOLEAN EXPRESSION] 

[LOOKING FOR COLLECTION OR DOMAIN NAME] 

[LOOKING FOR COLUMN HEADER] 

[LOOKING FOR CONSTANT] 

[LOOKING FOR DOMAIN NAME] 

[LOOKING FOR EDIT-STRING] 

[LOOKING FOR FIELD NAME] 

[LOOKING FOR FILE NAME FOR REPORT] 

[LOOKING FOR FILE NAME] 

[LOOKING FOR HEADER SEGMENT] 

[LOOKING FOR MATCHING PARENTHESIS] 

[LOOKING FOR NEXT ELEMENT IN LIST] 

[LOOKING FOR RELATIONAL EXPRESSION] 

[LOOKING FOR RELATIONAL OPERATOR (EQ, GT, ETC.)] 

[LOOKING FOR SORT LIST] 

[LOOKING FOR STATEMENT OR "END"] 

[LOOKING FOR STATEMENT] 

[LOOKING FOR UPPER VALUE OF BETWEEN] 

[SYNTAX ERROR--FLUSHING INPUT] 





APPENDIX E 


COBOL RULES 


DATATRIEVE-l1l uses a subset of COBOL rules in defining records, 
PICTURE character strings, and editing strings. The relevant rules 
have been extracted from the PDP-11 COBOL Language Reference Manual, 
and are summarized below with some tutorial material. For additional 
assistance, refer to the PDP-1l COBOL Language Reference Manual. 


The general format of a data-item definition in the record definition 
is given below. It consists of a number of elements that are covered 
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data-item-name 

level-no field-name-1 [PIC clause] 
EDIT-STRING-clause] 
USAGE-clause] 
SIGN-clause]. 


me "=e "tO 





The PICTURE clause defines the format of data as it will exist in the 
file. If no overriding edit-string clauses are specified, in either 
the record definition or PRINT command, then the PICTURE clause also 
controls the output format of the data. 
The PICTURE clause assumes the following format: 
PIC IS char-string 
The char-string is the part of the PICTURE clause that describes’ the 
number and type of characters expected in the data. The char-string 
is restricted to the symbols described in Table E-l. A number of 
examples follow: 
Example Field May Consist Of: 

PRICE PIC 99999 -- 5 digits 

LENGTH-OVER-ALL PIC XXX -- 3 alphabetic or numeric characters 

MANUFACTURER PIC X(10) -~~10 alphabetic or numeric characters 


PRICE PIC S9(5)V99 --7 digits;2 are tenths and hundredths 
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Table E-1l 
PICTURE Character-String Symbols 


Only digits (numbers 0 through 9) are permitted. 


Symbol 












Alphanumeric characters are permitted. 


The number carries a sign, but not necessarily 
in this location. 


Assumed decimal point location. 





(a number) Repeat the preceding symbol this many times. 





The USAGE clause applies to numerical data fields and defines’ the 


numerical data representation. The USAGE clause assumes the following 
format: 


USAGE IS uSage-string 


The usage-string may be any of the computational notations given in 
Table E-2. 


Table E-2 
USAGE Specifications 


Specification Meaning 


FORTRAN binary or BASIC-PLUS-2 integer 
short form floating point 

long form floating point 

DIBOL - signed decimal number 

COBOL binary 





Note that COMP-1 and COMP-2 are ueSe in FORTRAN and erase programs 


cat ”~ a - 1 
co réepresenct Single 2 precision real numbers, 


respectively. 





The SIGN clause expresses the location of the sign in a numeric field. 


SIGN IS Heat | [SEPARATE] 
c 


TRAILIN 


The permitted sign qualifiers are summarized in Table E-3. 


COBOL RULES 


Table E-3 
Sign Qualifiers 


LEADING The sign character is leftmost in the data field 


TRAILING The sign character is rightmost in the data field 

SEPARATE The sign character is a separate character in the 
number, and must be in either a leading or trailing 
position, as specified. 





Note that if the SIGN clause is not specified and the data field is 

numeric, it is assumed by default that the sign is TRAILING 

NON-SEPARATE. In other words, it is assumed the sign is represented 
by an "overpunch" in the rightmost digit. 





The EDIT-STRING clause, if present, specifies the format to be used to 
print a particular field. If the EDIT-STRING clause is not specified, 
the PIC clause is used to provide the printing format. 


The edit-string in the record definition assumes the following format: 
EDIT-STRING IS edit-string 
Edit-strings are also allowed in the PRINT commands, as part of the 


USING EDIT-STRING clause. The edit-string may consist of any of the 
characters in Table E-4. 


CLVUBVUL RULED 


Table E-4 
Edit-String Symbols 


a digit 










a blank character (if digit is 0) or ae significant 
digit 


a decimal point 





- a blank character if sign is positive or a minus’ sign 
(-) if sign is negative 


+ a minus sign if sign is negative or a plus sign (+) if 
sign is positive 


0 zero (0) 

B a blank character (space) 

/ a slash character (/) -- used in dates 

* an asterisk (*) if zero, or else a significant digit 

; acomma (,) if preceded by high-order significant 
digits, otherwise a blank character (space) 

$ a floating dollar sign--immediately precedes the first 


Significant digit 


(a number)| repeat the immediately preceding symbol this many 


times 

CR two blank characters if data is positive or CR if 
negative 

DB two blank characters if data is positive or DB if 
negative 


*,prompt-name, 4-25, 4-30, 
4-4], 4-57, 4-64 to 4-66, 
4-72, 5-4 

**,prompt-name, 4-25, 4-64 to 
4-66, 4-72 


A 


ABORT statement, 4-67, 4-71 
Access, 
modes, 4-21, 4-51 
modifiers, 4-2 
privileges, 4-9, 7-4, 7-7, 
7-13, 7-15, 7-17, 7-18 
Adding, 
entries to password table, 
7-22 
records, 4-54 
Advanced commands, 4-76 
Alphanumeric literals, 3-5 
Altering record formats, 7-30 
Arithmetic operations, 4-24 
ASCENDING, 4-29, 4-37 
Assignment statement, 4-55, 
4-62, 4-64 
Asterisk, 4-3, 4-9, 7-15, 7-24, 
7-26, 7-29, E-4 
AT statement, 5-6, 5-l1l 
Audit trail, 4-51 
Automatic tabs, 4-44 
AVERAGE, 4-25, 5-2, 5-11, 5-13 


B 
4%, viii 
BASIC-PLUS-2 integer, E-2 
BEGIN-END Block, 4-3, 4-55, 
4-62, 4-63, 4-65 
Black print, viii 
Blank, viii, E-4 
Boolean expressions, 4-23 
4-26, 4-69 
Boolean operator EQ, 4-65 
BOTTOM, 5-11 
BOTTOM OF PAGE, 5-11 
Braces, viii, 3-2 
Bracket, 
square, viii, 3-2 
syntax, viii, 3-2 
Buffer space, 4-38 


C 


Carriage return, 3-4, 3-6, 3-7, 
3-8, 4-9, 4-57 
Cataloguing a procedure, 7-9 


INDEX 


Changing record contents, 4-48 
Character, 
set, 3-4 
string, 4-24, 7-15 
Clause, 5-5 
Closing domains, 4-6 
COBOL, 
binary, E-2 
language, 7-2 
rules, 4-44, E-1l 
Coding password table 
entries, 7-19 
COL, 4-43, 5-13 
Collection, 1-3 
cursor, 1-3, 4-32, 4-41, 
4-74, 5-5 
empty, 4-33 
lifetime, 1-6 
name, 4-24, 4-29, 4-37 
naming, 4-19 
ordering, 1-6 
processing, 1-3 
sorting, 4-19 
Colon, 6-1 
Color, viii 
Column, 
header, 5-1, 5-12 
COLUMN-HEADER, 5-13 


COLUMNS-PAGE, 5-7 
Combining commands, 4-62, 4-67 
Comma, E-4 
Command, 1-3 
advanced, 4-76 
compound, 4-62, 4-67, 4-69 
element, 
recognition, 3-7 
sequence, 3-9 
files, indirect, 3-4, 7-1, 
7-4, 7-14 
names, 4-76 
simple, 4-76 
summary, B-l 
termination, 3-7 
Comments, 3-4 
COMP, E-2 
COMP-1, E-2 
COMP-2, E-2 
COMP-5, E-2 
COMP-6, E-2 
Compound, 
Boolean expression, 4-15, 
4-26 
command, 4-69 
statement, 4-33, 4-63, 4-71 
Concatenation character, 4-71, 
4-73 
Concurrent users, 4-19 
Condition, 4-23, 4-69 


Index-1 


INDEX (CONT.) 


Continuation, 
lines, 3-6 
of literals, 3-6 
of names, 3-6 
Control character, viii 
(see CTRL) 
COUNT, 4-25, 5-2, 5-11, 5-13 
CR, E-4 
CTRL, viii, 3-5 
O, 4-41 
Q, 4-41 
S, 4-41 
Z, 2-1, 4-6, 4-24, 4-50 
CURRENT, 
collection, 4-13, 4-34 
record, 1-5 
Cursor, collection, 1-3, 4-32, 
4-41, 4-74, 5-5 


D 


Data, 
checking, 4-50 
definition, 7-3 
editing, 4-65 
protection, 7-15 
restructuring, 4-65 
sample, 1-2 
Data-item, 7-3, E-l 
Data Dictionary, 1-3, 3-4, 4-8, 
6-1, 7-1, 7-13, 7-18 
DATE, 5-7 
Date of report, 5-7 
DB, E-4 
Decimal point, 3-5, E-4 
DECREASING, 4-29, 4-37 
DEFINE, 7-1 
DEFINEP, 7-15, 7-16, 7-18, 
7-23 
DEFINE DOMAIN, 7-7, 7-18, 7-30 
DEFINE PROCEDURE, 7-18 
DEFINE RECORD, 7-3, 7-18 


nay? 
Defining, 7+6 


domains, 7-7, 7-18, 7-30 
procedures, 7-9, 7-18 
records, 7-3, 7-18 
DELETE, 4-13, 7-4, 7-7, 7-18, 
7-25, 7-27 
DELETEP, 7-15, 7-16, 7-18, 
7-26 
Deleting, 


password tables, 7-27 
password table entries, 7-25 
procedure definitions, 7-12 
Delimiters, 3-8 
DESCENDING, 4-29, 4-37 
Detail line, 5-1, 5-10 
Dialogue, 1-1 
DIBOL signed-decimal number, E-2 
Displaying collections, 4-39 


DISPLAY statement, 4-71, 4-72 

Dollar sign, floating, E-4 

Domain definitions, 1-3, 4-7, 
7-1 

Domain finishing, 4-61 

Double-precision real 
numbers, E-2 


E 
Editing the Data Dictionary, 
7-1 
Edit-string, 4-44, 7-3, E-3 
EDIT-STRING clause, E-3 
Elementary data-item, 4-64, 
7-3 
Ellipsis, viii, 3-2 
Empty collection, 4-33 
END-PROCEDURE, 7-18 
English-like commands, 1-1 
Entering commands, 2-1 
Equals sign, 4-65 
ERASE, 4-38, 4-51 
Error messages, 2-1, D-1 
to D-7 
Establishing a collection, 4-13 
Exclamation point, 3-4 
EXCLUSIVE, 4-2 
EXIT, 2-1, 3-1, 4-5, 4-60, 4-61 
EXTEND mode, 4-2, 4-55, 4-64, 


7-30 
F 
Field, 1-2 
Field-name, 4-24, 4-41, 4-43, 
4-64 
Files, 1-3 
indirect command, 3-4, 7-1, 
7-4, 7-14 


FIND, 1-3, 4-13, 4-29, 4-60, 
4-61, 4-67, 4-74 
CURRENT, 4-17 
rse, 4-20 
FINISH, 4-38, 4-60, 4-61 
Finishing a domain, 4-61 
FIRST n, 4-20 
irst record, 1-5 
Floating dollar sign, E-4 
Formatted printouts, 4-40, 
4-45 
FOR loop, 4-65 
(see aiso FOR statement) 
FOR statement, 4-74, 7-30 
FORTRAN binary, E-2 
Free-form language, 3-1 


GC 
ww 


Getting assistance, 4-1, 4-76 


Index-2 
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Headers, 4-44, 5-1 
HELP, 4-1, 4-76 
Hyphens, 3-5, 3-6, 4-44 


IF-THEN-ELSE statement, 4-56, 
4-69, 4-71, 4-72 
INCREASING, 4-29, 4-37 
Indentation, 5-1 
Indexed sequential, 
files, 7-30 
records, 4-49 
Indirect command files, 3-4, 
7-1, 7-4, 7-14 
Integer, 4-24 
Interactive mode, 1-1 
Intermixing inquiry and RW 
statements, 1-2 
Invoking, 
procedures, 6-1 
RW, 5-4 


Keywords, 3-5, 3-7, 5-1, 7-4 


L 


Last record, 1-5 

LEADING, E-3 

Level numbers, 7-3, 7-30 
Lifetime of collection, 1-6 
LINES-PAGE, 5-7 

Literals, 3-5 

Long form floating point, E-2 
Looking at record contents, 4-39 
Lowercase words, viii, 3-2 


Maintaining password tables, 
7-25 
Matching names, 7-30 
MAX, 4-25, 5-2, 5-11, 5-13 
MAX-LINES, 5-7 
MAX-PAGES, 5-7 
Memory overhead, 4-58 
Message, 4-67, 4-71 
error or information, D-l 
to D-7 
MIN, 4-28, 5-2, 5-11, 5-13 
Minus sign, E-4 
Modes, 
access, 4-21, 4-51 
interactive, 1-1 


Modifiers, 
access, 4-2, 4-43 
print-list, 5-13 

MODIFY, 
access mode, 4-38, 4-48 
command, 4-2, 4-29, 4-48, 

4-57 

Multiple, 
collection cursors, 1-5, 4-34 
copies of reports, 5-5 
CURRENT records, 1-5 
RW sequences, 1-2 
SET statements, 5-8 


n, viii 
Names, 3-5 
collection, 4-19 
field, 4-24, 4-41, 4-43 
report, 5-7 
Nesting, 
IF-THEN-ELSE statements, 
4-70 
procedures, 7-18 
Syntax symbols, 3-2 
NEW-PAGE, 4-44, 5-11, 5-13 
NEW-SECTION, 5-11, 5-13 
Next record, 1-5 
NO=DATE, 5-7 
NO=NUMBER, 5-7 
Null, 1-5 
collection cursor, 4-34, 4-38 
NUMBER, 5-7 
Number of, 
columns, 5-7 
lines, 5-7 
Numbers, single- and double- 
precision, E-2 
Numeric literals, 3-5 


O 


OF clause, 4-25 

ON file-spec-1, 5-5 
Optional words, 3-2 
Ordering collections, 1-6 


p 


Page number, 5-1, 5-7 
Parts of a report, 5-1 
Password, 4-3, 4-8, 4-9, 4-51, 
7-13 
table, 4-4, 7-4, 7-7, 7-18 
design, 7-20 
entries, 7-15 
processing, 7-17 


& 
' 
OV 
ih 


Index-3 
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Period, 7-3 

PICTURE clause, 4-44, 7-3, 
E-1 

Plus sign, E-4 

Pointers, 4-38 


PPN, 7-15 
Primary key, 4-49 
PRINT, 


command, 4-29, 4-39, 4-40, 
4-42, 4-53, 4-72, E-l 
statement, 5-6, 5-10, 5-11 
Printing, 
format, E-3 
password tables, 7-28 
Print-list, 4-40, 4-43 
Privilege code, 7-16 
Procedure, 1-2, 4-62, 6-1 
definition, 1-3, 3-4, 4- 
7-1, 7-4, 7-7, 7-24 
name, 7-18 
Project, 
code, 7-17 
programmer number, 7-15 
Prompt-name 
(see *.prompt-—name) 
PROTECTED, 4-2, 4-3 
PW, 7-15 


3, 


QUERY-HEADER, 7-3 


QUERY-NAME, 4-64, 7-3, 7-30 
Ouotation mark, 3-5, 4-24 


R 


READ, 4-2, 4-38 
READY, 3-1, 4-1, 4-3, 4-14, 
4-21, 4-38, 4-49, 4-61, 
4-74, 7-18 
Record, 
definitions, 1-3, 4-7, 7-1. 
E-1 
name, 7-3 
number, 4-33 
pointer, 4-53 
selection expression, 4-20, 
4-28, 4-40, 4-49, 4-52, 
4-62, 4-74, 4-76, 5-4 
Records, 1-2 
Red print, viii 
Refining the collection, 4-16 
Relative files, 4-55, 7-30 
RELEASE, 4-38, 4-59, 4-61 
Releasing collections, 4-6, 
4-59 
Removing, 
password tables, 7-13 


records, 4=51 


REPEAT, 
loop, 4-65 
statement, 4-57, 4-62, 4-66 
REPORT, 1-2, 5-4 
Report, 
date, 5-7 
event, 5-2, 5-11, 5-12 
format checking, 5-5 
group, 5-1 
header, 5-1 . 
name, 5-1, 5-7 
parameter defaults, 5-9 
parts, 5-1 
section, 5-l 
title, 5-1 
REPORT END, 1-2, 3-1, 5-5, 5-6 
REPORT-HEADER, 5-13 
REPORT-NAME, 5-7 
Report Writer, 1-1, 4-40, 4-72, 
5-1, 5-5 
Required words, 3-2 
Resource name, 4-9 
Restructuring data, 4-65, 7-30 
RET, viii 
(see also carriage return) 
rse 
(see record selection 
expression) 
Rules, 
COBOL, E-1l to E-4 
precedence, 4-24 
RW sequence, 1-2, 5-1 


S 


Sample data, 1-2 
SELECT, 1-3, 4-33, 4-49, 
4-53, 4-67, 4-74 
Semicolon, 3-7, 7-3, 7-7, 
7-13, 7-18 
SEPARATE, E-3 
Sequence, 
number, 7-16 
of commands, 3-1 
Sequential, 
files, 7-30 
records, 4-52 
SET REPORT-NAME, 5-6 
SET statement, 5-7 
SHARED, 4-1, 4-2 
Short form floating point, 
E-2 
SHOW, 4-7, 7-5, 7-8, 7-18 
SHOWP, 7-16, 7-18, 7-29 
SHOW ALL, 4-20, 4-29 
SHOW COLLECTIONS, 4-19 
SHOW CURRENT, 4-34, 4-53 
SHOW PROCEDURES, 6-1 
SHOW READY, 4-4 


Index-4 


INDEX (CONT.) 


Show=item, 4=8 
SIGN clause, 7-3, E-2 
Simple, 
Boolean expression, 4-26 
command, 4-69, 4-76 
Single-precision real 
numbers, E-2 
SKIP, 4-43, 5-13 
Slash, 5-7, E-4 
SORT, 4-5, 4-36, 4-37 
SORTED BY clause, 4-21, 4-29, 
4-36, 4-53 
Sorting, 
collections, 4-19, 5-12 
facility, 4-36 
Sort-keys, 4-21, 4-29, 4-37 
Space, viii, 3-1, 3-7, 3-8, 
4-43, E-4 
considerations, 4-58 
Spacing, 3-1 
Spelling, 3-1 
Square brackets, viii 
Statements, 
ABORT, 4-67, 4-71 
assignment, 4-55, 4-62, 
4-64 
AT, 5-6, 5-11 
BEGIN-END, 4-3, 4-55, 4-62, 
4-63, 4-65 
DISPLAY, 4-71, 4-72 
FOR, 4-74, 7-30 
IF-THEN-ELSE, 4-56, 4-69, 
4-71, 4-72 
intermixing, 1-2 
PRINT, 5-6, 5-10, 5-11 
REPEAT, 4-57, 4-62, 4-66 
REPORT, 1-2, 5-4 
REPORT END, 5-13 
SET, 5-7 
THEN, 4-3, 4-67 
Statistical functions, 5-2, 
5-11 
STORE, 4-54, 4-63 to 4-65, © 
7-30 
Subtotals, 5-2 
Summary, 
items, 5-11 
lines, 5-2, 5-11 
Symbology, viii 
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Symbols, nested, 3-2 

Syntax, : 
brackets, viii, 3-2 
rules, 3-1 


T 


TAB, 4-43, 5-13 
Tab characters, 3-1, 3-7, 3-8 
automatic, 4-44 
Temporarily finding 
collections, 4-74 
Terminal device, 4-41, 4-71, 
7-29 
Terminating, 
DATATRIEVE (see EXIT) 
RW sequence, 5-6 
THEN statement, 4-3, 4-67 
TOP OF PAGE, 5-11 
Total, 4-28, 5-2 
TOTAL, 5-2, 5-11, 5-13 
TRAILING, E-3 


Truncation, 4-56, 4-64 
Types of locks, 7-15 
UIC, 7-15 


Underlining, viii, 3- 
Uppercase, viii, 3-2 
USAGE clause, 7-3, E- 
User, 
account number, 7-15 
identification code, 7-15 
USING, 4-44, 4-55 


2 
2 


V 


Value expression, 4-23, 4-24, 
4-43, 4-64, 4-66, 4-71, 
4-72, 5-11, 5-13 

VERIFY clause, 4-55 


W 


WRITE access mode, 4-2, 4-38, 
4-48, 4-52, 4-55, 4-64, 7-30 
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NOTE: This form is for document comments only. DIGITAL will 
use comments submitted on this form at the company's 
discretion. Problems with software should be reported 
on a Software Performance Report (SPR) form. If you 
require a written reply and are eligible to receive 
one under SPR service, submit your comments on an SPR 
form. 
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